Publish affix-huggingface 0.3.0

LICENSE

@@ -0,0 +1,202 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction,
+and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by
+the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all
+other entities that control, are controlled by, or are under common
+control with that entity. For the purposes of this definition,
+"control" means (i) the power, direct or indirect, to cause the
+direction or management of such entity, whether by contract or
+otherwise, or (ii) ownership of fifty percent (50%) or more of the
+outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity
+exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications,
+including but not limited to software source code, documentation
+source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical
+transformation or translation of a Source form, including but
+not limited to compiled object code, generated documentation,
+and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or
+Object form, made available under the License, as indicated by a
+copyright notice that is included in or attached to the work
+(an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object
+form, that is based on (or derived from) the Work and for which the
+editorial revisions, annotations, elaborations, or other modifications
+represent, as a whole, an original work of authorship. For the purposes
+of this License, Derivative Works shall not include works that remain
+separable from, or merely link (or bind by name) to the interfaces of,
+the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including
+the original version of the Work and any modifications or additions
+to that Work or Derivative Works thereof, that is intentionally
+submitted to Licensor for inclusion in the Work by the copyright owner
+or by an individual or Legal Entity authorized to submit on behalf of
+the copyright owner. For the purposes of this definition, "submitted"
+means any form of electronic, verbal, or written communication sent
+to the Licensor or its representatives, including but not limited to
+communication on electronic mailing lists, source code control systems,
+and issue tracking systems that are managed by, or on behalf of, the
+Licensor for the purpose of discussing and improving the Work, but
+excluding communication that is conspicuously marked or otherwise
+designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity
+on behalf of whom a Contribution has been received by Licensor and
+subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+copyright license to reproduce, prepare Derivative Works of,
+publicly display, publicly perform, sublicense, and distribute the
+Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+(except as stated in this section) patent license to make, have made,
+use, offer to sell, sell, import, and otherwise transfer the Work,
+where such license applies only to those patent claims licensable
+by such Contributor that are necessarily infringed by their
+Contribution(s) alone or by combination of their Contribution(s)
+with the Work to which such Contribution(s) was submitted. If You
+institute patent litigation against any entity (including a
+cross-claim or counterclaim in a lawsuit) alleging that the Work
+or a Contribution incorporated within the Work constitutes direct
+or contributory patent infringement, then any patent licenses
+granted to You under this License for that Work shall terminate
+as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+Work or Derivative Works thereof in any medium, with or without
+modifications, and in Source or Object form, provided that You
+meet the following conditions:
+
+(a) You must give any other recipients of the Work or
+Derivative Works a copy of this License; and
+
+(b) You must cause any modified files to carry prominent notices
+stating that You changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works
+that You distribute, all copyright, patent, trademark, and
+attribution notices from the Source form of the Work,
+excluding those notices that do not pertain to any part of
+the Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its
+distribution, then any Derivative Works that You distribute must
+include a readable copy of the attribution notices contained
+within such NOTICE file, excluding those notices that do not
+pertain to any part of the Derivative Works, in at least one
+of the following places: within a NOTICE text file distributed
+as part of the Derivative Works; within the Source form or
+documentation, if provided along with the Derivative Works; or,
+within a display generated by the Derivative Works, if and
+wherever such third-party notices normally appear. The contents
+of the NOTICE file are for informational purposes only and
+do not modify the License. You may add Your own attribution
+notices within Derivative Works that You distribute, alongside
+or as an addendum to the NOTICE text from the Work, provided
+that such additional attribution notices cannot be construed
+as modifying the License.
+
+You may add Your own copyright statement to Your modifications and
+may provide additional or different license terms and conditions
+for use, reproduction, or distribution of Your modifications, or
+for any such Derivative Works as a whole, provided Your use,
+reproduction, and distribution of the Work otherwise complies with
+the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+any Contribution intentionally submitted for inclusion in the Work
+by You to the Licensor shall be under the terms and conditions of
+this License, without any additional terms or conditions.
+Notwithstanding the above, nothing herein shall supersede or modify
+the terms of any separate license agreement you may have executed
+with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+names, trademarks, service marks, or product names of the Licensor,
+except as required for reasonable and customary use in describing the
+origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+agreed to in writing, Licensor provides the Work (and each
+Contributor provides its Contributions) on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+implied, including, without limitation, any warranties or conditions
+of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+PARTICULAR PURPOSE. You are solely responsible for determining the
+appropriateness of using or redistributing the Work and assume any
+risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+whether in tort (including negligence), contract, or otherwise,
+unless required by applicable law (such as deliberate and grossly
+negligent acts) or agreed to in writing, shall any Contributor be
+liable to You for damages, including any direct, indirect, special,
+incidental, or consequential damages of any character arising as a
+result of this License or out of the use or inability to use the
+Work (including but not limited to damages for loss of goodwill,
+work stoppage, computer failure or malfunction, or any and all
+other commercial damages or losses), even if such Contributor has
+been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+the Work or Derivative Works thereof, You may choose to offer,
+and charge a fee for, acceptance of support, warranty, indemnity,
+or other liability obligations and/or rights consistent with this
+License. However, in accepting such obligations, You may act only
+on Your own behalf and on Your sole responsibility, not on behalf
+of any other Contributor, and only if You agree to indemnify,
+defend, and hold each Contributor harmless for any liability
+incurred by, or claims asserted against, such Contributor by reason
+of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+To apply the Apache License to your work, attach the following
+boilerplate notice, with the fields enclosed by brackets "[]"
+replaced with your own identifying information. (Don't include
+the brackets!) The text should be enclosed in the appropriate
+comment syntax for the file format. We also recommend that a
+file or class name and description of purpose be included on the
+same "printed page" as the copyright notice for easier
+identification within third-party archives.
+
+Copyright [yyyy] [name of copyright owner]
+
+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.
+

SECURITY.md

@@ -0,0 +1,34 @@
+# Security
+
+## The published trial key
+
+`PUBLIC_TRIAL_API_KEY` ships inside the package. It is published, not secret. Anyone who installs the wheel can read it, so it is scoped, rate limited, and revocable, and it carries no customer data access.
+
+No SDK can hide a credential from the machine it runs on. If the code can send a key to AffixIO, the user can read it. Treat any key embedded in a distributed package as public, and keep production keys in the runtime secret store.
+
+## Trial allowance
+
+The 100 proof allowance is enforced on `api.affix-io.com` against a subject digest. The local file under `~/.cache/affix-huggingface/` holds install credentials only. Deleting it forces re-registration against the same server-side counter rather than granting new proofs.
+
+Local counters cannot be made tamper proof. Anything written to a user's disk can be deleted, and a fresh container or virtual machine always looks new. Server-side counting is what makes the limit hold.
+
+Creating a second identity still yields a second allowance. New subject registrations are throttled per origin. Where the limit must resist deliberate evasion, bind registration to a verified Hub account.
+
+## Credentials
+
+Load `AFFIX_API_KEY` and `HF_TOKEN` from the runtime secret store. Do not put either value in source control, container images, notebooks, model cards, or Hugging Face Spaces variables marked public.
+
+The SDK sends the AffixIO key only to the configured AffixIO base URL and the Hugging Face token only through `huggingface_hub`.
+
+Changing `affix_base_url` transfers the AffixIO key to that host. Treat this setting as security-sensitive and keep the default in production unless you operate the destination.
+
+## Data boundary
+
+The SDK does not include prompt or output content in AffixIO prove, gate, or attestation requests. Model identifiers, declared revision metadata, gate receipts, proof digests, model-binding digests, and the trial subject digest are sent to AffixIO. The Hugging Face account name and token are not.
+
+Customer applications are responsible for calculating `AdmissionChecks` from trusted records. Supplying `True` values without evaluating those records weakens admission to a caller assertion.
+
+## Reporting
+
+Report suspected vulnerabilities privately to security@affix-io.com. Include the affected version and a minimal reproduction. Do not include production API keys, Hugging Face tokens, prompts, or customer data.
+

dist/affix_huggingface-0.3.0.tar.gz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:1b9116ecfde753be31ca9a4e5cbefc041c889177cc8324179b5dd7490eac348f
+size 26006

examples/chat_completion.py

@@ -0,0 +1,33 @@
+"""Run an AffixIO-authorised Hugging Face chat completion."""
+
+# Credit: @paparichens
+
+from affix_huggingface import AdmissionChecks, AffixHuggingFace, ModelRef
+
+
+def main() -> None:
+    model = ModelRef(
+        model_id="meta-llama/Llama-3.1-8B-Instruct",
+        provider="hf-inference",
+    )
+    checks = AdmissionChecks(
+        entitled=True,
+        data_route_allowed=True,
+        controls_satisfied=True,
+    )
+
+    with AffixHuggingFace() as client:
+        result = client.chat_completion(
+            [{"role": "user", "content": "Summarise the supplied operational note."}],
+            model=model,
+            checks=checks,
+            max_tokens=150,
+        )
+
+    print(result.output)
+    print(f"AffixIO receipt: {result.receipt.gate.receipt_id}")
+
+
+if __name__ == "__main__":
+    main()
+

hatch_build.py

@@ -0,0 +1,62 @@
+"""Build hook that ships an integrity manifest inside the wheel.
+
+The manifest hashes every packaged file. At runtime the package recomputes those
+hashes and refuses to run if any differ. The manifest is written to a temporary
+path and force-included, so the source tree stays clean and editable installs
+remain unenforced.
+"""
+
+# Credit: @paparichens
+
+from __future__ import annotations
+
+import hashlib
+import json
+import tempfile
+from pathlib import Path
+from typing import Any
+
+from hatchling.builders.hooks.plugin.interface import BuildHookInterface
+
+PACKAGE = "affix_huggingface"
+MANIFEST_NAME = "_integrity_manifest.json"
+ALGORITHM = "sha256"
+_SKIP_SUFFIXES = (".pyc", ".pyo")
+_SKIP_DIRS = {"__pycache__"}
+
+
+def _hash_file(path: Path) -> str:
+    digest = hashlib.new(ALGORITHM)
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(65536), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+class CustomBuildHook(BuildHookInterface):
+    PLUGIN_NAME = "custom"
+
+    def initialize(self, version: str, build_data: dict[str, Any]) -> None:
+        if self.target_name != "wheel":
+            return
+
+        root = Path(self.root) / "src" / PACKAGE
+        files: dict[str, str] = {}
+        for path in sorted(root.rglob("*")):
+            if not path.is_file():
+                continue
+            rel = path.relative_to(root)
+            if any(part in _SKIP_DIRS for part in rel.parts):
+                continue
+            if path.suffix in _SKIP_SUFFIXES:
+                continue
+            if path.name == MANIFEST_NAME:
+                continue
+            files[rel.as_posix()] = _hash_file(path)
+
+        manifest = {"version": 1, "algorithm": ALGORITHM, "files": files}
+        tmp = Path(tempfile.mkdtemp(prefix="affix-manifest-")) / MANIFEST_NAME
+        tmp.write_text(json.dumps(manifest, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+
+        force_include = build_data.setdefault("force_include", {})
+        force_include[str(tmp)] = f"{PACKAGE}/{MANIFEST_NAME}"

pyproject.toml

@@ -0,0 +1,73 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "affix-huggingface"
+version = "0.3.0"
+description = "AffixIO admission and evidence controls for Hugging Face inference."
+readme = "README.md"
+license = { text = "Apache-2.0" }
+requires-python = ">=3.10"
+authors = [{ name = "AffixIO", email = "hello@affix-io.com" }]
+keywords = [
+  "affixio",
+  "huggingface",
+  "inference",
+  "admission-control",
+  "verification",
+  "ml-dsa",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: Apache Software License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed",
+]
+dependencies = [
+  "httpx>=0.27,<1",
+  "huggingface-hub>=1.0,<2",
+]
+
+[project.optional-dependencies]
+dev = [
+  "build",
+  "mypy",
+  "pytest",
+  "pytest-cov",
+  "ruff",
+]
+
+[project.urls]
+Homepage = "https://www.affix-io.com/"
+API = "https://api.affix-io.com/"
+Credentials = "https://hub.affix-io.com/credentials/"
+HuggingFace = "https://huggingface.co/"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/affix_huggingface"]
+
+[tool.hatch.build.hooks.custom]
+path = "hatch_build.py"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+packages = ["affix_huggingface"]
+

src/affix_huggingface/__init__.py

@@ -0,0 +1,58 @@
+"""AffixIO admission and evidence controls for Hugging Face inference."""
+
+# Credit: @paparichens
+
+from .integrity import IntegrityError  # noqa: I001
+from .integrity import enforce as _enforce_integrity
+
+_enforce_integrity()
+
+from .client import AffixHuggingFace, AuthorisedStream  # noqa: E402
+from .errors import (  # noqa: E402
+    AdmissionDenied,
+    AffixAPIError,
+    AffixHuggingFaceError,
+    ConfigurationError,
+    EvidenceError,
+    RegistrationThrottled,
+    StreamNotComplete,
+    TrialExhausted,
+)
+from .models import (  # noqa: E402
+    AdmissionChecks,
+    AdmissionProof,
+    AffixReceipt,
+    AuthorisedResult,
+    CompletionEvidence,
+    GateReceipt,
+    ModelRef,
+)
+from .trial import TrialCredentials, TrialQuota, credentials_path  # noqa: E402
+
+__version__ = "0.3.0"
+
+__all__ = [
+    "AdmissionChecks",
+    "AdmissionDenied",
+    "AdmissionProof",
+    "AffixAPIError",
+    "AffixHuggingFace",
+    "AffixHuggingFaceError",
+    "AffixReceipt",
+    "AuthorisedResult",
+    "AuthorisedStream",
+    "CompletionEvidence",
+    "ConfigurationError",
+    "EvidenceError",
+    "GateReceipt",
+    "IntegrityError",
+    "ModelRef",
+    "RegistrationThrottled",
+    "StreamNotComplete",
+    "TrialCredentials",
+    "TrialExhausted",
+    "TrialQuota",
+    "__version__",
+    "credentials_path",
+]
+

src/affix_huggingface/client.py

@@ -0,0 +1,544 @@
+"""Hugging Face inference guarded by AffixIO internet admission."""
+
+# Credit: @paparichens
+
+from __future__ import annotations
+
+import os
+import uuid
+from collections.abc import Callable, Iterable, Iterator, Mapping
+from datetime import datetime, timezone
+from typing import Any, Generic, Protocol, TypeVar, cast
+
+from huggingface_hub import InferenceClient
+
+from .errors import AdmissionDenied, ConfigurationError, EvidenceError, StreamNotComplete
+from .integrity import ensure_intact
+from .models import (
+    AdmissionChecks,
+    AdmissionProof,
+    AffixReceipt,
+    AuthorisedResult,
+    CompletionEvidence,
+    EvidenceMode,
+    GateMode,
+    GateReceipt,
+    ModelRef,
+)
+from .transport import AffixTransport
+from .trial import (
+    PUBLIC_TRIAL_API_KEY,
+    TRIAL_PRODUCT,
+    TrialQuota,
+    load_credentials,
+    resolve_subject,
+    save_credentials,
+)
+
+T = TypeVar("T")
+
+
+class InferenceClientProtocol(Protocol):
+    """Subset of Hugging Face's client used by this SDK."""
+
+    def chat_completion(
+        self,
+        messages: list[dict[str, Any]],
+        *,
+        model: str,
+        **kwargs: Any,
+    ) -> Any: ...
+
+    def text_generation(self, prompt: str, *, model: str, **kwargs: Any) -> Any: ...
+
+    def feature_extraction(self, text: str | list[str], *, model: str, **kwargs: Any) -> Any: ...
+
+
+class AuthorisedStream(Generic[T], Iterator[T]):
+    """Iterator that issues final evidence after the HF stream completes."""
+
+    def __init__(
+        self,
+        source: Iterable[T],
+        *,
+        admission_receipt: AffixReceipt,
+        finalise: Callable[[], AffixReceipt],
+    ) -> None:
+        self._source = iter(source)
+        self._finalise = finalise
+        self.admission_receipt = admission_receipt
+        self._final_receipt: AffixReceipt | None = None
+        self._complete = False
+
+    def __iter__(self) -> AuthorisedStream[T]:
+        return self
+
+    def __next__(self) -> T:
+        try:
+            return next(self._source)
+        except StopIteration:
+            self._complete_stream()
+            raise
+
+    @property
+    def complete(self) -> bool:
+        return self._complete
+
+    @property
+    def final_receipt(self) -> AffixReceipt:
+        if self._final_receipt is None:
+            raise StreamNotComplete("Consume the stream before requesting its final receipt")
+        return self._final_receipt
+
+    def close(self) -> None:
+        close = getattr(self._source, "close", None)
+        if callable(close):
+            close()
+
+    def _complete_stream(self) -> None:
+        if self._complete:
+            return
+        self._final_receipt = self._finalise()
+        self._complete = True
+
+
+class AffixHuggingFace:
+    """
+    Cloud-to-cloud AffixIO admission around Hugging Face inference.
+
+    Prompt and output content are supplied only to the Hugging Face client.
+    AffixIO receives proof material and metadata about the model binding.
+    """
+
+    def __init__(
+        self,
+        *,
+        affix_api_key: str | None = None,
+        hf_token: str | None = None,
+        affix_base_url: str = "https://api.affix-io.com",
+        hf_provider: str | None = None,
+        timeout: float = 30.0,
+        max_retries: int = 2,
+        evidence_mode: EvidenceMode = "required",
+        subject: str | None = None,
+        trial: bool | None = None,
+        affix_transport: AffixTransport | None = None,
+        hf_client: InferenceClientProtocol | None = None,
+    ) -> None:
+        supplied_key = affix_api_key or os.getenv("AFFIX_API_KEY")
+        token = hf_token or os.getenv("HF_TOKEN")
+        ensure_intact()
+        api_key = supplied_key or PUBLIC_TRIAL_API_KEY
+        if not token and hf_client is None:
+            raise ConfigurationError("HF_TOKEN is required for Hugging Face inference")
+        if evidence_mode not in {"required", "best_effort", "off"}:
+            raise ValueError("evidence_mode must be required, best_effort, or off")
+
+        if trial is None:
+            trial = affix_transport is None and supplied_key is None
+
+        self.evidence_mode = evidence_mode
+        self._trial = trial
+        self._subject = subject
+        self._hf_token = token
+        self._registered = False
+        self._owns_affix = affix_transport is None
+        self._owns_hf = hf_client is None
+        self._affix = affix_transport or AffixTransport(
+            api_key or "",
+            base_url=affix_base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+        )
+        self._hf = hf_client or cast(
+            InferenceClientProtocol,
+            InferenceClient(
+                token=token,
+                provider=hf_provider,  # type: ignore[arg-type]
+                timeout=timeout,
+            ),
+        )
+
+    def close(self) -> None:
+        if self._owns_affix:
+            self._affix.close()
+        if self._owns_hf:
+            close = getattr(self._hf, "close", None)
+            if callable(close):
+                close()
+
+    def __enter__(self) -> AffixHuggingFace:
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+    def health(self) -> Mapping[str, Any]:
+        data, _ = self._affix.health()
+        return data
+
+    @property
+    def quota(self) -> TrialQuota | None:
+        """Allowance reported by the last AffixIO response, if any."""
+        return self._affix.last_quota
+
+    def refresh_quota(self) -> TrialQuota:
+        """Ask AffixIO for the current allowance for this subject."""
+        self._ensure_registered()
+        return self._affix.quota()
+
+    def _ensure_registered(self) -> None:
+        """
+        Attach install credentials before the first metered call.
+
+        Cached credentials are a convenience. The allowance itself is counted
+        per subject on api.affix-io.com, so clearing the cache re-registers
+        against the same counter rather than granting new proofs.
+        """
+        if not self._trial or self._registered:
+            return
+
+        cached = load_credentials()
+        if cached is not None:
+            self._affix.credentials = cached
+            self._registered = True
+            return
+
+        subject_id = resolve_subject(subject=self._subject, hf_token=self._hf_token)
+        credentials, _ = self._affix.register_install(
+            subject_id=subject_id,
+            product=TRIAL_PRODUCT,
+        )
+        save_credentials(credentials)
+        self._affix.credentials = credentials
+        self._registered = True
+
+    def prove_admission(
+        self,
+        checks: AdmissionChecks,
+        *,
+        circuit_id: str = "yesno",
+        idempotency_key: str | None = None,
+    ) -> AdmissionProof:
+        self._ensure_registered()
+        data, _ = self._affix.prove(
+            circuit_id=circuit_id,
+            fields=checks.prove_fields(),
+            idempotency_key=idempotency_key or self._key("prove"),
+        )
+        proof = data.get("proof")
+        if not isinstance(proof, str) or not proof:
+            raise ConfigurationError("AffixIO prove response did not contain proof material")
+        return AdmissionProof(proof=proof, circuit_id=circuit_id, policy_id="gate.agent")
+
+    def inspect(
+        self,
+        model: ModelRef,
+        *,
+        proof: AdmissionProof,
+        idempotency_key: str | None = None,
+    ) -> GateReceipt:
+        """Verify without spending. This method never calls Hugging Face."""
+        return self._gate(
+            model,
+            proof=proof,
+            mode="check",
+            idempotency_key=idempotency_key or self._key("inspect"),
+        )
+
+    def authorise(
+        self,
+        model: ModelRef,
+        *,
+        checks: AdmissionChecks | None = None,
+        proof: AdmissionProof | None = None,
+        idempotency_key: str | None = None,
+        valid_from: int | None = None,
+        valid_until: int | None = None,
+        region_hash: str | None = None,
+        region_expected: str | None = None,
+    ) -> GateReceipt:
+        """Consume one valid proof before an inference call."""
+        root_key = idempotency_key or uuid.uuid4().hex
+        if proof is None:
+            if checks is None:
+                raise ConfigurationError("Provide checks or a pre-issued admission proof")
+            proof = self.prove_admission(
+                checks,
+                idempotency_key=f"{root_key}:prove",
+            )
+        receipt = self._gate(
+            model,
+            proof=proof,
+            mode="consume",
+            idempotency_key=f"{root_key}:gate",
+            valid_from=valid_from,
+            valid_until=valid_until,
+            region_hash=region_hash,
+            region_expected=region_expected,
+        )
+        if not receipt.allow:
+            raise AdmissionDenied(
+                "AffixIO denied the Hugging Face inference request",
+                reason_code=receipt.reason_code,
+                receipt_id=receipt.receipt_id,
+                request_id=receipt.request_id,
+            )
+        return receipt
+
+    def chat_completion(
+        self,
+        messages: list[dict[str, Any]],
+        *,
+        model: ModelRef,
+        checks: AdmissionChecks | None = None,
+        proof: AdmissionProof | None = None,
+        idempotency_key: str | None = None,
+        **kwargs: Any,
+    ) -> AuthorisedResult:
+        if kwargs.get("stream"):
+            raise ValueError("Use stream_chat_completion for streaming responses")
+        return self._execute(
+            "chat_completion",
+            model,
+            checks=checks,
+            proof=proof,
+            idempotency_key=idempotency_key,
+            invoke=lambda: self._hf.chat_completion(
+                messages,
+                model=model.inference_target,
+                **kwargs,
+            ),
+        )
+
+    def text_generation(
+        self,
+        prompt: str,
+        *,
+        model: ModelRef,
+        checks: AdmissionChecks | None = None,
+        proof: AdmissionProof | None = None,
+        idempotency_key: str | None = None,
+        **kwargs: Any,
+    ) -> AuthorisedResult:
+        if kwargs.get("stream"):
+            raise ValueError("Use stream_text_generation for streaming responses")
+        return self._execute(
+            "text_generation",
+            model,
+            checks=checks,
+            proof=proof,
+            idempotency_key=idempotency_key,
+            invoke=lambda: self._hf.text_generation(
+                prompt,
+                model=model.inference_target,
+                **kwargs,
+            ),
+        )
+
+    def feature_extraction(
+        self,
+        text: str | list[str],
+        *,
+        model: ModelRef,
+        checks: AdmissionChecks | None = None,
+        proof: AdmissionProof | None = None,
+        idempotency_key: str | None = None,
+        **kwargs: Any,
+    ) -> AuthorisedResult:
+        return self._execute(
+            "feature_extraction",
+            model,
+            checks=checks,
+            proof=proof,
+            idempotency_key=idempotency_key,
+            invoke=lambda: self._hf.feature_extraction(
+                text,
+                model=model.inference_target,
+                **kwargs,
+            ),
+        )
+
+    def stream_chat_completion(
+        self,
+        messages: list[dict[str, Any]],
+        *,
+        model: ModelRef,
+        checks: AdmissionChecks | None = None,
+        proof: AdmissionProof | None = None,
+        idempotency_key: str | None = None,
+        **kwargs: Any,
+    ) -> AuthorisedStream[Any]:
+        kwargs.pop("stream", None)
+        gate = self.authorise(
+            model,
+            checks=checks,
+            proof=proof,
+            idempotency_key=idempotency_key,
+        )
+        source = self._hf.chat_completion(
+            messages,
+            model=model.inference_target,
+            stream=True,
+            **kwargs,
+        )
+        return self._stream("chat_completion", model, gate, source)
+
+    def stream_text_generation(
+        self,
+        prompt: str,
+        *,
+        model: ModelRef,
+        checks: AdmissionChecks | None = None,
+        proof: AdmissionProof | None = None,
+        idempotency_key: str | None = None,
+        **kwargs: Any,
+    ) -> AuthorisedStream[Any]:
+        kwargs.pop("stream", None)
+        gate = self.authorise(
+            model,
+            checks=checks,
+            proof=proof,
+            idempotency_key=idempotency_key,
+        )
+        source = self._hf.text_generation(
+            prompt,
+            model=model.inference_target,
+            stream=True,
+            **kwargs,
+        )
+        return self._stream("text_generation", model, gate, source)
+
+    def _execute(
+        self,
+        operation: str,
+        model: ModelRef,
+        *,
+        checks: AdmissionChecks | None,
+        proof: AdmissionProof | None,
+        idempotency_key: str | None,
+        invoke: Callable[[], Any],
+    ) -> AuthorisedResult:
+        gate = self.authorise(
+            model,
+            checks=checks,
+            proof=proof,
+            idempotency_key=idempotency_key,
+        )
+        output = invoke()
+        receipt = self._finalise(operation, model, gate, output=output)
+        return AuthorisedResult(output=output, receipt=receipt)
+
+    def _stream(
+        self,
+        operation: str,
+        model: ModelRef,
+        gate: GateReceipt,
+        source: Any,
+    ) -> AuthorisedStream[Any]:
+        admission = AffixReceipt(model=model, operation=operation, gate=gate)
+        return AuthorisedStream(
+            source,
+            admission_receipt=admission,
+            finalise=lambda: self._finalise(operation, model, gate),
+        )
+
+    def _gate(
+        self,
+        model: ModelRef,
+        *,
+        proof: AdmissionProof,
+        mode: GateMode,
+        idempotency_key: str,
+        valid_from: int | None = None,
+        valid_until: int | None = None,
+        region_hash: str | None = None,
+        region_expected: str | None = None,
+    ) -> GateReceipt:
+        self._ensure_registered()
+        data, request_id = self._affix.gate(
+            proof=proof.proof,
+            circuit_id=proof.circuit_id,
+            policy_id=proof.policy_id,
+            mode=mode,
+            gate_id=model.binding_digest,
+            idempotency_key=idempotency_key,
+            valid_from=valid_from,
+            valid_until=valid_until,
+            region_hash=region_hash,
+            region_expected=region_expected,
+        )
+        return GateReceipt.from_response(data, request_id=request_id)
+
+    def _finalise(
+        self,
+        operation: str,
+        model: ModelRef,
+        gate: GateReceipt,
+        *,
+        output: Any = None,
+    ) -> AffixReceipt:
+        if self.evidence_mode == "off":
+            return AffixReceipt(model=model, operation=operation, gate=gate)
+
+        payload: dict[str, Any] = {
+            "schema": "affix-huggingface-receipt-v1",
+            "decision": "yes",
+            "operation": operation,
+            "model_id": model.model_id,
+            "model_revision": model.revision,
+            "hosting": model.hosting,
+            "provider": model.provider,
+            "model_binding_sha256": model.binding_digest,
+            "gate_receipt_id": gate.receipt_id,
+            "gate_proof_digest": gate.proof_digest,
+            "hf_response_id": self._response_id(output),
+            "completed_at": datetime.now(timezone.utc).isoformat(),
+            "prompt_included": False,
+            "output_included": False,
+        }
+        payload = {key: value for key, value in payload.items() if value is not None}
+        try:
+            data, request_id = self._affix.attest(
+                payload,
+                idempotency_key=self._key("completion"),
+            )
+            attestation = data.get("attestation")
+            if not isinstance(attestation, Mapping):
+                raise ConfigurationError("AffixIO attest response did not contain an attestation")
+            completion = CompletionEvidence(
+                payload=payload,
+                attestation=dict(attestation),
+                request_id=request_id,
+            )
+            return AffixReceipt(
+                model=model,
+                operation=operation,
+                gate=gate,
+                completion=completion,
+            )
+        except Exception as exc:
+            if self.evidence_mode == "required":
+                raise EvidenceError(
+                    "Hugging Face inference completed, but AffixIO evidence failed",
+                    output=output,
+                    cause=exc,
+                ) from exc
+            return AffixReceipt(
+                model=model,
+                operation=operation,
+                gate=gate,
+                evidence_error=str(exc),
+            )
+
+    @staticmethod
+    def _response_id(output: Any) -> str | None:
+        value = getattr(output, "id", None)
+        if value is None and isinstance(output, Mapping):
+            value = output.get("id")
+        return str(value) if value is not None else None
+
+    @staticmethod
+    def _key(operation: str) -> str:
+        return f"hf-sdk:{operation}:{uuid.uuid4().hex}"
+

src/affix_huggingface/errors.py

@@ -0,0 +1,98 @@
+"""Exceptions raised by the AffixIO Hugging Face SDK."""
+
+# Credit: @paparichens
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class AffixHuggingFaceError(Exception):
+    """Base SDK error."""
+
+
+class ConfigurationError(AffixHuggingFaceError):
+    """Required credentials or configuration are missing."""
+
+
+class AffixAPIError(AffixHuggingFaceError):
+    """The AffixIO API returned an error response."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int,
+        code: str | None = None,
+        request_id: str | None = None,
+        body: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.code = code
+        self.request_id = request_id
+        self.body = body or {}
+
+
+class AdmissionDenied(AffixHuggingFaceError):
+    """AffixIO refused the inference request before Hugging Face was called."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        reason_code: str,
+        receipt_id: str | None = None,
+        request_id: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.reason_code = reason_code
+        self.receipt_id = receipt_id
+        self.request_id = request_id
+
+
+UPGRADE_STEPS = (
+    "Your free allowance is used up. To continue with your own key:\n"
+    "  1. Register at https://hub.affix-io.com/ and request API access.\n"
+    "  2. Access is granted after review, not instantly.\n"
+    "  3. Once approved, create a key at https://hub.affix-io.com/credentials/\n"
+    "  4. Set AFFIX_API_KEY=aio_... and run again. Your key has no trial cap."
+)
+
+
+class TrialExhausted(AffixHuggingFaceError):
+    """The server-side proof allowance for this subject has been used up."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        limit: int,
+        used: int,
+        request_id: str | None = None,
+    ) -> None:
+        super().__init__(f"{message}\n\n{UPGRADE_STEPS}")
+        self.limit = limit
+        self.used = used
+        self.remaining = 0
+        self.request_id = request_id
+        self.upgrade_url = "https://hub.affix-io.com/"
+        self.upgrade_steps = UPGRADE_STEPS
+
+
+class RegistrationThrottled(AffixHuggingFaceError):
+    """AffixIO refused to register another new subject from this origin today."""
+
+
+class EvidenceError(AffixHuggingFaceError):
+    """Inference completed, but completion evidence could not be issued."""
+
+    def __init__(self, message: str, *, output: Any, cause: Exception) -> None:
+        super().__init__(message)
+        self.output = output
+        self.__cause__ = cause
+
+
+class StreamNotComplete(AffixHuggingFaceError):
+    """A final stream receipt was requested before the stream finished."""
+

src/affix_huggingface/integrity.py

@@ -0,0 +1,125 @@
+"""Fail-closed integrity guard.
+
+A signed file manifest ships inside the built wheel. On import the package
+recomputes the hash of every shipped file and compares it to the manifest. Any
+edit, overwrite, added file, or removed file trips the guard: the package marks
+itself bricked and refuses to run.
+
+Honest limit: this is tamper-evident, not tamper-proof. A user who edits the
+guard itself, or deletes the manifest, disables the check, because the code runs
+on their machine. No client-side mechanism can prevent that. What this does
+guarantee is that any accidental or casual modification of a shipped file stops
+the product working rather than running altered code silently.
+
+The manifest is generated at build time (see hatch_build.py) and is absent from
+the source tree, so an editable development checkout is not enforced.
+"""
+
+# Credit: @paparichens
+
+from __future__ import annotations
+
+import hashlib
+import json
+from collections.abc import Iterator
+from pathlib import Path
+
+MANIFEST_NAME = "_integrity_manifest.json"
+MANIFEST_ALGORITHM = "sha256"
+_SKIP_SUFFIXES = (".pyc", ".pyo")
+_SKIP_DIRS = frozenset({"__pycache__"})
+
+_bricked_reason: str | None = None
+
+
+class IntegrityError(RuntimeError):
+    """Raised when a shipped file has been altered, added, or removed."""
+
+
+def _iter_files(root: Path) -> Iterator[Path]:
+    for path in sorted(root.rglob("*")):
+        if not path.is_file():
+            continue
+        if any(part in _SKIP_DIRS for part in path.relative_to(root).parts):
+            continue
+        if path.suffix in _SKIP_SUFFIXES:
+            continue
+        if path.name == MANIFEST_NAME:
+            continue
+        yield path
+
+
+def _hash_file(path: Path) -> str:
+    digest = hashlib.new(MANIFEST_ALGORITHM)
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(65536), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def build_manifest(root: Path) -> dict[str, object]:
+    """Compute the manifest for a package directory."""
+    files = {
+        str(path.relative_to(root).as_posix()): _hash_file(path)
+        for path in _iter_files(root)
+    }
+    return {"version": 1, "algorithm": MANIFEST_ALGORITHM, "files": files}
+
+
+def verify_tree(root: Path) -> None:
+    """
+    Verify a package directory against its manifest.
+
+    No manifest present means an unbuilt or editable tree, which is not
+    enforced. A present manifest is enforced strictly.
+    """
+    manifest_path = root / MANIFEST_NAME
+    if not manifest_path.exists():
+        return
+
+    try:
+        manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+        expected = dict(manifest["files"])
+    except (OSError, ValueError, KeyError, TypeError) as exc:
+        raise IntegrityError("Integrity manifest is unreadable or malformed") from exc
+
+    actual = {
+        str(path.relative_to(root).as_posix()): _hash_file(path)
+        for path in _iter_files(root)
+    }
+
+    added = sorted(set(actual) - set(expected))
+    removed = sorted(set(expected) - set(actual))
+    changed = sorted(
+        name for name in expected.keys() & actual.keys() if expected[name] != actual[name]
+    )
+
+    if added or removed or changed:
+        parts = []
+        if changed:
+            parts.append(f"modified: {', '.join(changed)}")
+        if removed:
+            parts.append(f"missing: {', '.join(removed)}")
+        if added:
+            parts.append(f"unexpected: {', '.join(added)}")
+        raise IntegrityError(
+            "Package integrity check failed (" + "; ".join(parts) + "). "
+            "A shipped file was altered. Reinstall a clean copy: "
+            "pip install --force-reinstall affix-huggingface"
+        )
+
+
+def enforce() -> None:
+    """Run the guard for this installed package and remember the outcome."""
+    global _bricked_reason
+    try:
+        verify_tree(Path(__file__).resolve().parent)
+    except IntegrityError as exc:
+        _bricked_reason = str(exc)
+        raise
+
+
+def ensure_intact() -> None:
+    """Refuse to proceed once the guard has tripped."""
+    if _bricked_reason is not None:
+        raise IntegrityError(_bricked_reason)

src/affix_huggingface/models.py

@@ -0,0 +1,185 @@
+"""Public value objects for AffixIO-controlled Hugging Face inference."""
+
+# Credit: @paparichens
+
+from __future__ import annotations
+
+import hashlib
+import json
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+HostingClass = Literal["hf_inference", "inference_endpoint", "self_hosted_tgi"]
+GateMode = Literal["check", "consume"]
+EvidenceMode = Literal["required", "best_effort", "off"]
+
+
+@dataclass(frozen=True)
+class ModelRef:
+    """
+    A Hugging Face model or remote Inference Endpoint.
+
+    ``revision`` is declared audit metadata. Hugging Face's public inference
+    call does not accept a revision pin, so use a pinned dedicated endpoint
+    where exact deployed weights are required.
+    """
+
+    model_id: str
+    revision: str | None = None
+    endpoint_url: str | None = None
+    provider: str | None = None
+    hosting: HostingClass = "hf_inference"
+
+    def __post_init__(self) -> None:
+        if not self.model_id.strip():
+            raise ValueError("model_id must not be empty")
+        if self.endpoint_url and not self.endpoint_url.startswith("https://"):
+            raise ValueError("endpoint_url must use HTTPS")
+
+    @property
+    def inference_target(self) -> str:
+        return self.endpoint_url or self.model_id
+
+    def binding(self) -> dict[str, str]:
+        values = {
+            "model_id": self.model_id,
+            "revision": self.revision,
+            "endpoint_url": self.endpoint_url,
+            "provider": self.provider,
+            "hosting": self.hosting,
+        }
+        return {key: value for key, value in values.items() if value is not None}
+
+    @property
+    def binding_digest(self) -> str:
+        canonical = json.dumps(
+            self.binding(),
+            sort_keys=True,
+            separators=(",", ":"),
+            ensure_ascii=True,
+        ).encode("utf-8")
+        return hashlib.sha256(canonical).hexdigest()
+
+
+@dataclass(frozen=True)
+class AdmissionChecks:
+    """
+    Customer-evaluated predicates submitted for remote AffixIO proving.
+
+    These values contain no prompt, output, or subject identifier. Applications
+    remain responsible for evaluating their own entitlement and policy records.
+    """
+
+    entitled: bool
+    data_route_allowed: bool
+    controls_satisfied: bool
+
+    @property
+    def allow_hint(self) -> bool:
+        return self.entitled and self.data_route_allowed and self.controls_satisfied
+
+    def prove_fields(self) -> dict[str, bool]:
+        return {
+            "condition_greater1": self.entitled,
+            "condition_greater2": self.data_route_allowed,
+            "condition_greater3": self.controls_satisfied,
+        }
+
+
+@dataclass(frozen=True)
+class AdmissionProof:
+    """Proof material accepted by the AffixIO gate."""
+
+    proof: str
+    circuit_id: str = "yesno"
+    policy_id: str = "gate.agent"
+
+    def __post_init__(self) -> None:
+        if not self.proof.strip():
+            raise ValueError("proof must not be empty")
+
+
+@dataclass(frozen=True)
+class GateReceipt:
+    """AffixIO admission response retained alongside an HF result."""
+
+    allow: bool
+    reason_code: str
+    receipt_id: str | None
+    request_id: str | None
+    proof_digest: str | None
+    proof_ref: str | None
+    policy_id: str | None
+    policy_version: str | None
+    mode: str | None
+    spent: bool
+    merkle_root: str | None
+    merkle_leaf_hash: str | None
+    attestation: Mapping[str, Any] | None
+    raw: Mapping[str, Any] = field(repr=False)
+
+    @classmethod
+    def from_response(
+        cls,
+        data: Mapping[str, Any],
+        *,
+        request_id: str | None,
+    ) -> GateReceipt:
+        return cls(
+            allow=bool(data.get("allow", False)),
+            reason_code=str(data.get("reason_code") or data.get("error") or "UNKNOWN"),
+            receipt_id=_optional_str(data.get("receipt_id")),
+            request_id=request_id,
+            proof_digest=_optional_str(data.get("proof_digest")),
+            proof_ref=_optional_str(data.get("proof_ref")),
+            policy_id=_optional_str(data.get("policy_id")),
+            policy_version=_optional_str(data.get("policy_version")),
+            mode=_optional_str(data.get("mode")),
+            spent=bool(data.get("spent", False)),
+            merkle_root=_optional_str(data.get("merkle_root")),
+            merkle_leaf_hash=_optional_str(data.get("merkle_leaf_hash")),
+            attestation=_mapping_or_none(data.get("attestation")),
+            raw=dict(data),
+        )
+
+
+@dataclass(frozen=True)
+class CompletionEvidence:
+    """Post-inference AffixIO attestation over metadata only."""
+
+    payload: Mapping[str, Any]
+    attestation: Mapping[str, Any]
+    request_id: str | None
+
+
+@dataclass(frozen=True)
+class AffixReceipt:
+    """Admission and optional post-inference evidence."""
+
+    model: ModelRef
+    operation: str
+    gate: GateReceipt
+    completion: CompletionEvidence | None = None
+    evidence_error: str | None = None
+
+
+@dataclass(frozen=True)
+class AuthorisedResult:
+    """Hugging Face output paired with its AffixIO receipt."""
+
+    output: Any
+    receipt: AffixReceipt
+
+
+def _optional_str(value: Any) -> str | None:
+    if value is None:
+        return None
+    return str(value)
+
+
+def _mapping_or_none(value: Any) -> Mapping[str, Any] | None:
+    if isinstance(value, Mapping):
+        return dict(value)
+    return None
+

src/affix_huggingface/py.typed

@@ -0,0 +1 @@
+

src/affix_huggingface/transport.py

@@ -0,0 +1,286 @@
+"""Authenticated HTTPS transport for the AffixIO production API."""
+
+# Credit: @paparichens
+
+from __future__ import annotations
+
+import time
+from collections.abc import Mapping
+from typing import Any
+from urllib.parse import quote
+
+import httpx
+
+from .errors import AffixAPIError, RegistrationThrottled, TrialExhausted
+from .trial import TrialCredentials, TrialQuota
+
+RETRYABLE_STATUS = frozenset({429, 502, 503, 504})
+USER_AGENT = "affix-huggingface/0.3.0"
+
+
+class AffixTransport:
+    """Small production transport with bounded, idempotent retries."""
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = "https://api.affix-io.com",
+        timeout: float = 30.0,
+        max_retries: int = 2,
+        client: httpx.Client | None = None,
+        credentials: TrialCredentials | None = None,
+    ) -> None:
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max(0, max_retries)
+        self.credentials = credentials
+        self.last_quota: TrialQuota | None = None
+        self._owns_client = client is None
+        self._client = client or httpx.Client(
+            base_url=self.base_url,
+            timeout=timeout,
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "X-API-Key": api_key,
+                "Accept": "application/json",
+                "User-Agent": USER_AGENT,
+            },
+        )
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._client.close()
+
+    def __enter__(self) -> AffixTransport:
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+    def health(self) -> tuple[dict[str, Any], str | None]:
+        return self._request("GET", "/api/health")
+
+    def register_install(
+        self,
+        *,
+        subject_id: str,
+        product: str,
+        label: str | None = None,
+    ) -> tuple[TrialCredentials, TrialQuota | None]:
+        """Claim or rejoin the server-side allowance for a subject."""
+        body: dict[str, Any] = {"subject": subject_id, "product": product}
+        if label:
+            body["label"] = label
+        data, _ = self._request("POST", "/v1/trial/register", json=body)
+        credentials = TrialCredentials(
+            install_id=str(data["install_id"]),
+            install_secret=str(data["install_secret"]),
+            subject_id=str(data.get("subject_id", subject_id)),
+            product=str(data.get("product", product)),
+        )
+        raw_quota = data.get("quota")
+        quota = (
+            TrialQuota(
+                limit=int(raw_quota["limit"]),
+                used=int(raw_quota["used"]),
+                remaining=int(raw_quota["remaining"]),
+            )
+            if isinstance(raw_quota, Mapping)
+            else None
+        )
+        return credentials, quota
+
+    def quota(self) -> TrialQuota:
+        """Current allowance for the authenticated install."""
+        data, _ = self._request("GET", "/v1/trial/quota")
+        return TrialQuota(
+            limit=int(data["limit"]),
+            used=int(data["used"]),
+            remaining=int(data["remaining"]),
+        )
+
+    def prove(
+        self,
+        *,
+        circuit_id: str,
+        fields: Mapping[str, str | int | bool],
+        idempotency_key: str,
+        sector: str = "huggingface_inference",
+    ) -> tuple[dict[str, Any], str | None]:
+        body = {
+            "fields": dict(fields),
+            "requestAttestation": True,
+            "sector": sector,
+        }
+        return self._request(
+            "POST",
+            f"/v1/circuits/{quote(circuit_id, safe='')}/prove",
+            json=body,
+            idempotency_key=idempotency_key,
+        )
+
+    def gate(
+        self,
+        *,
+        proof: str,
+        circuit_id: str,
+        policy_id: str,
+        mode: str,
+        gate_id: str,
+        idempotency_key: str,
+        valid_from: int | None = None,
+        valid_until: int | None = None,
+        region_hash: str | None = None,
+        region_expected: str | None = None,
+    ) -> tuple[dict[str, Any], str | None]:
+        body: dict[str, Any] = {
+            "proof": proof,
+            "circuit_id": circuit_id,
+            "policy_id": policy_id,
+            "mode": mode,
+            "gate_id": gate_id,
+            "entry_point": "hf-sdk",
+            "requestAttestation": True,
+            "sector": "huggingface_inference",
+        }
+        optional = {
+            "valid_from": valid_from,
+            "valid_until": valid_until,
+            "region_hash": region_hash,
+            "region_expected": region_expected,
+        }
+        body.update({key: value for key, value in optional.items() if value is not None})
+        return self._request(
+            "POST",
+            "/v1/gate/verify",
+            json=body,
+            idempotency_key=idempotency_key,
+            accept_gate_denial=True,
+        )
+
+    def attest(
+        self,
+        payload: Mapping[str, Any],
+        *,
+        idempotency_key: str,
+    ) -> tuple[dict[str, Any], str | None]:
+        return self._request(
+            "POST",
+            "/api/attest",
+            json={"payload": dict(payload)},
+            idempotency_key=idempotency_key,
+        )
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Mapping[str, Any] | None = None,
+        idempotency_key: str | None = None,
+        accept_gate_denial: bool = False,
+    ) -> tuple[dict[str, Any], str | None]:
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "X-API-Key": self.api_key,
+            "Accept": "application/json",
+            "User-Agent": USER_AGENT,
+        }
+        if idempotency_key:
+            headers["Idempotency-Key"] = idempotency_key
+        if self.credentials is not None:
+            headers.update(self.credentials.headers())
+        last_transport_error: httpx.TransportError | None = None
+
+        for attempt in range(self.max_retries + 1):
+            try:
+                response = self._client.request(
+                    method,
+                    self._url(path),
+                    json=json,
+                    headers=headers,
+                    timeout=self.timeout,
+                )
+            except httpx.TransportError as exc:
+                last_transport_error = exc
+                if attempt >= self.max_retries:
+                    raise AffixAPIError(
+                        f"AffixIO transport failed: {exc}",
+                        status_code=0,
+                        code="transport_error",
+                    ) from exc
+                self._sleep(attempt, None)
+                continue
+
+            data = self._json_object(response)
+            request_id = response.headers.get("X-Request-Id")
+            quota = TrialQuota.from_headers(response.headers)
+            if quota is not None:
+                self.last_quota = quota
+            if response.status_code < 400:
+                return data, request_id
+            self._raise_for_trial(data, request_id)
+            if accept_gate_denial and data.get("allow") is False:
+                return data, request_id
+            if response.status_code in RETRYABLE_STATUS and attempt < self.max_retries:
+                self._sleep(attempt, response.headers.get("Retry-After"))
+                continue
+            raise AffixAPIError(
+                str(data.get("message") or data.get("error") or f"HTTP {response.status_code}"),
+                status_code=response.status_code,
+                code=str(data.get("error") or f"http_{response.status_code}"),
+                request_id=request_id,
+                body=data,
+            )
+
+        raise AffixAPIError(
+            f"AffixIO transport failed: {last_transport_error}",
+            status_code=0,
+            code="transport_error",
+        )
+
+    @staticmethod
+    def _raise_for_trial(data: Mapping[str, Any], request_id: str | None) -> None:
+        error = str(data.get("error") or "")
+        if error == "trial_exhausted":
+            limit = int(data.get("limit") or 0)
+            used = int(data.get("used") or limit)
+            raise TrialExhausted(
+                str(data.get("message") or "Trial allowance used up"),
+                limit=limit,
+                used=used,
+                request_id=request_id,
+            )
+        if error == "registration_throttled":
+            raise RegistrationThrottled(
+                str(data.get("message") or "Too many new trial subjects from this origin")
+            )
+
+    def _url(self, path: str) -> str:
+        if self._owns_client:
+            return path
+        return f"{self.base_url}{path}"
+
+    @staticmethod
+    def _json_object(response: httpx.Response) -> dict[str, Any]:
+        try:
+            data = response.json()
+        except ValueError:
+            return {"error": "invalid_json", "message": response.text[:500]}
+        if isinstance(data, dict):
+            return data
+        return {"data": data}
+
+    @staticmethod
+    def _sleep(attempt: int, retry_after: str | None) -> None:
+        if retry_after:
+            try:
+                delay = min(max(float(retry_after), 0.0), 5.0)
+            except ValueError:
+                delay = 0.25 * (2**attempt)
+        else:
+            delay = 0.25 * (2**attempt)
+        time.sleep(delay)
+

src/affix_huggingface/trial.py

@@ -0,0 +1,177 @@
+"""Trial install registration and the local credential cache.
+
+The proof allowance is counted on api.affix-io.com against a subject digest.
+Files written here are a cache. Deleting them forces re-registration against
+the same server-side counter and does not restore spent proofs.
+"""
+
+# Credit: @paparichens
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from .errors import ConfigurationError
+
+TRIAL_PRODUCT = "huggingface"
+
+# Published trial key. It ships inside the package, so treat it as public:
+# it is scoped, rate limited, and revocable. Supply AFFIX_API_KEY for
+# production use.
+PUBLIC_TRIAL_API_KEY = "aio_50754e6f66c7a573a46a16a52e1b1edffba48c395b708316"
+
+
+@dataclass(frozen=True)
+class TrialCredentials:
+    """Install credentials issued by AffixIO and cached locally."""
+
+    install_id: str
+    install_secret: str
+    subject_id: str
+    product: str = TRIAL_PRODUCT
+
+    def headers(self) -> dict[str, str]:
+        return {
+            "X-Affix-Install-Id": self.install_id,
+            "X-Affix-Install-Secret": self.install_secret,
+        }
+
+    def to_dict(self) -> dict[str, str]:
+        return {
+            "install_id": self.install_id,
+            "install_secret": self.install_secret,
+            "subject_id": self.subject_id,
+            "product": self.product,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> TrialCredentials | None:
+        try:
+            return cls(
+                install_id=str(data["install_id"]),
+                install_secret=str(data["install_secret"]),
+                subject_id=str(data["subject_id"]),
+                product=str(data.get("product", TRIAL_PRODUCT)),
+            )
+        except (KeyError, TypeError):
+            return None
+
+
+@dataclass(frozen=True)
+class TrialQuota:
+    """Allowance reported by AffixIO."""
+
+    limit: int
+    used: int
+    remaining: int
+
+    @property
+    def exhausted(self) -> bool:
+        return self.remaining <= 0
+
+    @classmethod
+    def from_headers(cls, headers: Any) -> TrialQuota | None:
+        try:
+            limit = headers.get("X-Affix-Trial-Limit")
+            used = headers.get("X-Affix-Trial-Used")
+            remaining = headers.get("X-Affix-Trial-Remaining")
+        except AttributeError:
+            return None
+        if limit is None or used is None or remaining is None:
+            return None
+        try:
+            return cls(limit=int(limit), used=int(used), remaining=int(remaining))
+        except (TypeError, ValueError):
+            return None
+
+
+def credentials_path() -> Path:
+    """Cache location for install credentials."""
+    override = os.getenv("AFFIX_INSTALL_FILE")
+    if override:
+        return Path(override).expanduser()
+    base = os.getenv("XDG_CACHE_HOME")
+    root = Path(base).expanduser() if base else Path.home() / ".cache"
+    return root / "affix-huggingface" / "install.json"
+
+
+def load_credentials(path: Path | None = None) -> TrialCredentials | None:
+    target = path or credentials_path()
+    try:
+        raw = json.loads(target.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return None
+    if not isinstance(raw, dict):
+        return None
+    return TrialCredentials.from_dict(raw)
+
+
+def save_credentials(credentials: TrialCredentials, path: Path | None = None) -> None:
+    target = path or credentials_path()
+    try:
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(
+            json.dumps(credentials.to_dict(), indent=2) + "\n",
+            encoding="utf-8",
+        )
+        target.chmod(0o600)
+    except OSError:
+        # A read-only cache directory costs a registration round trip per run,
+        # it does not grant extra proofs.
+        return
+
+
+def subject_digest(raw: str) -> str:
+    """Hash a subject locally so the identity itself never leaves the host."""
+    value = raw.strip().lower()
+    if not value:
+        raise ConfigurationError("Trial subject must not be empty")
+    return hashlib.sha256(f"affix-hf-subject:{value}".encode()).hexdigest()
+
+
+def resolve_subject(
+    *,
+    subject: str | None = None,
+    hf_token: str | None = None,
+) -> str:
+    """
+    Determine the identity the allowance is counted against.
+
+    Order of preference: explicit subject, AFFIX_TRIAL_SUBJECT, then the
+    Hugging Face account behind the token. Resolution fails closed, because a
+    random fallback would hand out a fresh allowance on every install.
+    """
+    explicit = subject or os.getenv("AFFIX_TRIAL_SUBJECT")
+    if explicit:
+        return subject_digest(explicit)
+
+    token = hf_token or os.getenv("HF_TOKEN")
+    if not token:
+        raise ConfigurationError(
+            "Cannot determine a trial subject. Set HF_TOKEN so the Hugging Face "
+            "account can be resolved, or pass subject= explicitly."
+        )
+
+    try:
+        from huggingface_hub import whoami
+
+        info = whoami(token=token)
+    except Exception as exc:
+        raise ConfigurationError(
+            "Could not resolve the Hugging Face account for the trial allowance. "
+            "Pass subject= explicitly if this host cannot reach huggingface.co."
+        ) from exc
+
+    name = None
+    if isinstance(info, dict):
+        name = info.get("id") or info.get("name")
+    else:
+        name = getattr(info, "id", None) or getattr(info, "name", None)
+    if not name:
+        raise ConfigurationError("Hugging Face account lookup returned no identity")
+    return subject_digest(f"hf:{name}")

tests/test_client.py

@@ -0,0 +1,211 @@
+"""Network-free contract tests for the AffixIO Hugging Face SDK."""
+
+# Credit: @paparichens
+
+from __future__ import annotations
+
+from typing import Any
+
+import pytest
+
+from affix_huggingface import (
+    AdmissionChecks,
+    AdmissionDenied,
+    AdmissionProof,
+    AffixHuggingFace,
+    ModelRef,
+    StreamNotComplete,
+)
+
+
+class FakeAffixTransport:
+    def __init__(self, *, allow: bool = True) -> None:
+        self.allow = allow
+        self.prove_calls: list[dict[str, Any]] = []
+        self.gate_calls: list[dict[str, Any]] = []
+        self.attest_calls: list[dict[str, Any]] = []
+
+    def close(self) -> None:
+        return None
+
+    def health(self) -> tuple[dict[str, Any], str | None]:
+        return {"ok": True}, "req_health"
+
+    def prove(self, **kwargs: Any) -> tuple[dict[str, Any], str | None]:
+        self.prove_calls.append(kwargs)
+        return {"proof": "proof_hex", "valid": True}, "req_prove"
+
+    def gate(self, **kwargs: Any) -> tuple[dict[str, Any], str | None]:
+        self.gate_calls.append(kwargs)
+        return (
+            {
+                "allow": self.allow,
+                "reason_code": "ADMITTED" if self.allow else "INVALID_PROOF",
+                "receipt_id": "rcpt_1",
+                "proof_digest": "abc123",
+                "proof_ref": "1:abc123",
+                "policy_id": "gate.agent",
+                "policy_version": "2026.08",
+                "mode": kwargs["mode"],
+                "spent": self.allow and kwargs["mode"] == "consume",
+                "merkle_root": "root_1",
+                "merkle_leaf_hash": "leaf_1",
+                "attestation": {"algorithm": "ML-DSA-65"},
+            },
+            "req_gate",
+        )
+
+    def attest(self, payload: dict[str, Any], **kwargs: Any) -> tuple[dict[str, Any], str | None]:
+        self.attest_calls.append({"payload": payload, **kwargs})
+        return {"attestation": {"algorithm": "ML-DSA-65", "signature": "sig"}}, "req_attest"
+
+
+class FakeHfClient:
+    def __init__(self) -> None:
+        self.calls: list[dict[str, Any]] = []
+
+    def chat_completion(
+        self,
+        messages: list[dict[str, Any]],
+        *,
+        model: str,
+        **kwargs: Any,
+    ) -> dict[str, Any] | list[str]:
+        self.calls.append(
+            {"method": "chat_completion", "messages": messages, "model": model, **kwargs}
+        )
+        if kwargs.get("stream"):
+            return ["token-1", "token-2"]
+        return {"id": "hf_response_1", "choices": []}
+
+    def text_generation(self, prompt: str, *, model: str, **kwargs: Any) -> str | list[str]:
+        self.calls.append(
+            {"method": "text_generation", "prompt": prompt, "model": model, **kwargs}
+        )
+        if kwargs.get("stream"):
+            return ["first", "second"]
+        return "generated"
+
+    def feature_extraction(
+        self,
+        text: str | list[str],
+        *,
+        model: str,
+        **kwargs: Any,
+    ) -> list[list[float]]:
+        self.calls.append(
+            {"method": "feature_extraction", "text": text, "model": model, **kwargs}
+        )
+        return [[0.1, 0.2]]
+
+
+def make_client(
+    *,
+    affix: FakeAffixTransport | None = None,
+    hf: FakeHfClient | None = None,
+    evidence_mode: str = "required",
+) -> tuple[AffixHuggingFace, FakeAffixTransport, FakeHfClient]:
+    affix = affix or FakeAffixTransport()
+    hf = hf or FakeHfClient()
+    client = AffixHuggingFace(
+        affix_transport=affix,  # type: ignore[arg-type]
+        hf_client=hf,
+        evidence_mode=evidence_mode,  # type: ignore[arg-type]
+    )
+    return client, affix, hf
+
+
+def test_model_binding_is_deterministic_and_excludes_content() -> None:
+    model = ModelRef(
+        model_id="org/model",
+        revision="abc",
+        provider="hf-inference",
+    )
+    assert len(model.binding_digest) == 64
+    assert model.binding_digest == ModelRef(
+        model_id="org/model",
+        revision="abc",
+        provider="hf-inference",
+    ).binding_digest
+    assert "prompt" not in model.binding()
+
+
+def test_denial_happens_before_hugging_face_call() -> None:
+    client, _, hf = make_client(affix=FakeAffixTransport(allow=False))
+    with pytest.raises(AdmissionDenied) as exc:
+        client.chat_completion(
+            [{"role": "user", "content": "private prompt"}],
+            model=ModelRef("org/model"),
+            proof=AdmissionProof("bad-proof"),
+        )
+    assert exc.value.reason_code == "INVALID_PROOF"
+    assert hf.calls == []
+
+
+def test_authorised_chat_returns_output_and_evidence() -> None:
+    client, affix, hf = make_client()
+    result = client.chat_completion(
+        [{"role": "user", "content": "private prompt"}],
+        model=ModelRef("org/model", revision="commit-sha"),
+        proof=AdmissionProof("proof_hex"),
+        max_tokens=20,
+    )
+
+    assert result.output["id"] == "hf_response_1"
+    assert result.receipt.gate.allow is True
+    assert result.receipt.completion is not None
+    assert hf.calls[0]["messages"][0]["content"] == "private prompt"
+    assert "private prompt" not in repr(affix.gate_calls)
+    assert "private prompt" not in repr(affix.attest_calls)
+    assert affix.attest_calls[0]["payload"]["prompt_included"] is False
+    assert affix.attest_calls[0]["payload"]["output_included"] is False
+
+
+def test_checks_use_remote_prove_then_consume() -> None:
+    client, affix, _ = make_client(evidence_mode="off")
+    client.text_generation(
+        "private input",
+        model=ModelRef("org/model"),
+        checks=AdmissionChecks(
+            entitled=True,
+            data_route_allowed=True,
+            controls_satisfied=True,
+        ),
+    )
+    assert affix.prove_calls[0]["fields"] == {
+        "condition_greater1": True,
+        "condition_greater2": True,
+        "condition_greater3": True,
+    }
+    assert affix.gate_calls[0]["mode"] == "consume"
+    assert "private input" not in repr(affix.prove_calls)
+    assert "private input" not in repr(affix.gate_calls)
+
+
+def test_stream_attests_only_after_consumption() -> None:
+    client, affix, _ = make_client()
+    stream = client.stream_text_generation(
+        "private input",
+        model=ModelRef("org/model"),
+        proof=AdmissionProof("proof_hex"),
+    )
+    with pytest.raises(StreamNotComplete):
+        _ = stream.final_receipt
+    assert affix.attest_calls == []
+    assert list(stream) == ["first", "second"]
+    assert stream.complete is True
+    assert stream.final_receipt.completion is not None
+    assert len(affix.attest_calls) == 1
+
+
+def test_inspect_does_not_call_hugging_face() -> None:
+    client, affix, hf = make_client(evidence_mode="off")
+    receipt = client.inspect(
+        ModelRef("org/model"),
+        proof=AdmissionProof("proof_hex"),
+    )
+    assert receipt.allow is True
+    assert receipt.mode == "check"
+    assert affix.gate_calls[0]["mode"] == "check"
+    assert hf.calls == []
+

tests/test_integrity.py

@@ -0,0 +1,82 @@
+"""Integrity guard: matching manifest passes, any change bricks."""
+
+# Credit: @paparichens
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+
+from affix_huggingface.integrity import (
+    MANIFEST_NAME,
+    IntegrityError,
+    build_manifest,
+    verify_tree,
+)
+
+
+def _package(root: Path) -> Path:
+    pkg = root / "pkg"
+    pkg.mkdir()
+    (pkg / "__init__.py").write_text("VALUE = 1\n", encoding="utf-8")
+    (pkg / "core.py").write_text("def run():\n    return True\n", encoding="utf-8")
+    (pkg / "py.typed").write_text("\n", encoding="utf-8")
+    return pkg
+
+
+def _write_manifest(pkg: Path) -> None:
+    manifest = build_manifest(pkg)
+    (pkg / MANIFEST_NAME).write_text(json.dumps(manifest), encoding="utf-8")
+
+
+def test_unbuilt_tree_without_manifest_is_not_enforced(tmp_path: Path) -> None:
+    pkg = _package(tmp_path)
+    verify_tree(pkg)  # no manifest, no raise
+
+
+def test_matching_manifest_passes(tmp_path: Path) -> None:
+    pkg = _package(tmp_path)
+    _write_manifest(pkg)
+    verify_tree(pkg)
+
+
+def test_editing_a_file_bricks(tmp_path: Path) -> None:
+    pkg = _package(tmp_path)
+    _write_manifest(pkg)
+    (pkg / "core.py").write_text("def run():\n    return False\n", encoding="utf-8")
+    with pytest.raises(IntegrityError, match="modified"):
+        verify_tree(pkg)
+
+
+def test_adding_a_file_bricks(tmp_path: Path) -> None:
+    pkg = _package(tmp_path)
+    _write_manifest(pkg)
+    (pkg / "extra.py").write_text("x = 1\n", encoding="utf-8")
+    with pytest.raises(IntegrityError, match="unexpected"):
+        verify_tree(pkg)
+
+
+def test_removing_a_file_bricks(tmp_path: Path) -> None:
+    pkg = _package(tmp_path)
+    _write_manifest(pkg)
+    (pkg / "core.py").unlink()
+    with pytest.raises(IntegrityError, match="missing"):
+        verify_tree(pkg)
+
+
+def test_corrupt_manifest_bricks(tmp_path: Path) -> None:
+    pkg = _package(tmp_path)
+    (pkg / MANIFEST_NAME).write_text("{ not json", encoding="utf-8")
+    with pytest.raises(IntegrityError, match="malformed"):
+        verify_tree(pkg)
+
+
+def test_manifest_excludes_itself_and_pyc(tmp_path: Path) -> None:
+    pkg = _package(tmp_path)
+    _write_manifest(pkg)
+    cache = pkg / "__pycache__"
+    cache.mkdir()
+    (cache / "core.cpython-312.pyc").write_bytes(b"\x00\x01")
+    verify_tree(pkg)  # bytecode and manifest are ignored

tests/test_transport.py

@@ -0,0 +1,99 @@
+"""Transport contracts for the AffixIO production API client."""
+
+# Credit: @paparichens
+
+from __future__ import annotations
+
+import httpx
+import pytest
+
+from affix_huggingface.errors import AffixAPIError
+from affix_huggingface.transport import AffixTransport
+
+
+def test_prove_sends_auth_idempotency_and_encoded_circuit() -> None:
+    captured: list[httpx.Request] = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        captured.append(request)
+        return httpx.Response(
+            200,
+            json={"proof": "proof_hex"},
+            headers={"X-Request-Id": "req_1"},
+        )
+
+    http = httpx.Client(transport=httpx.MockTransport(handler))
+    transport = AffixTransport("aio_test", client=http)
+    data, request_id = transport.prove(
+        circuit_id="yes/no",
+        fields={"condition_greater1": True},
+        idempotency_key="idem_1",
+    )
+
+    assert data["proof"] == "proof_hex"
+    assert request_id == "req_1"
+    assert captured[0].url.raw_path == b"/v1/circuits/yes%2Fno/prove"
+    assert captured[0].headers["Authorization"] == "Bearer aio_test"
+    assert captured[0].headers["X-API-Key"] == "aio_test"
+    assert captured[0].headers["Idempotency-Key"] == "idem_1"
+
+
+def test_gate_returns_structured_denial_from_403() -> None:
+    def handler(_: httpx.Request) -> httpx.Response:
+        return httpx.Response(
+            403,
+            json={
+                "allow": False,
+                "reason_code": "REGION_MISMATCH",
+                "receipt_id": "rcpt_denied",
+            },
+        )
+
+    http = httpx.Client(transport=httpx.MockTransport(handler))
+    transport = AffixTransport("aio_test", client=http)
+    data, _ = transport.gate(
+        proof="proof_hex",
+        circuit_id="yesno",
+        policy_id="gate.agent",
+        mode="consume",
+        gate_id="a" * 64,
+        idempotency_key="idem_gate",
+    )
+    assert data["allow"] is False
+    assert data["reason_code"] == "REGION_MISMATCH"
+
+
+def test_retryable_response_is_retried(monkeypatch: pytest.MonkeyPatch) -> None:
+    attempts = 0
+
+    def handler(_: httpx.Request) -> httpx.Response:
+        nonlocal attempts
+        attempts += 1
+        if attempts == 1:
+            return httpx.Response(503, json={"error": "unavailable"})
+        return httpx.Response(200, json={"ok": True})
+
+    monkeypatch.setattr(AffixTransport, "_sleep", staticmethod(lambda *_: None))
+    http = httpx.Client(transport=httpx.MockTransport(handler))
+    transport = AffixTransport("aio_test", client=http, max_retries=1)
+    data, _ = transport.health()
+    assert data == {"ok": True}
+    assert attempts == 2
+
+
+def test_non_retryable_error_preserves_api_fields() -> None:
+    def handler(_: httpx.Request) -> httpx.Response:
+        return httpx.Response(
+            401,
+            json={"error": "unauthorised", "message": "API key rejected"},
+            headers={"X-Request-Id": "req_auth"},
+        )
+
+    http = httpx.Client(transport=httpx.MockTransport(handler))
+    transport = AffixTransport("bad_key", client=http)
+    with pytest.raises(AffixAPIError) as exc:
+        transport.health()
+    assert exc.value.status_code == 401
+    assert exc.value.code == "unauthorised"
+    assert exc.value.request_id == "req_auth"
+

tests/test_trial.py

@@ -0,0 +1,323 @@
+"""Trial allowance behaviour, including reinstall and exhaustion."""
+
+# Credit: @paparichens
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import httpx
+import pytest
+from test_client import FakeHfClient
+
+from affix_huggingface import (
+    AdmissionChecks,
+    AdmissionProof,
+    AffixHuggingFace,
+    ModelRef,
+    TrialExhausted,
+)
+from affix_huggingface.errors import ConfigurationError, RegistrationThrottled
+from affix_huggingface.transport import AffixTransport
+from affix_huggingface.trial import (
+    TrialCredentials,
+    load_credentials,
+    resolve_subject,
+    save_credentials,
+    subject_digest,
+)
+
+PASSING_CHECKS = AdmissionChecks(
+    entitled=True,
+    data_route_allowed=True,
+    controls_satisfied=True,
+)
+
+
+class FakeQuotaServer:
+    """Minimal stand-in for the AffixIO trial endpoints."""
+
+    def __init__(self, *, limit: int = 100) -> None:
+        self.limit = limit
+        self.subject_used: dict[str, int] = {}
+        self.installs: dict[str, str] = {}
+        self.install_counter = 0
+        self.registrations = 0
+
+    def handler(self, request: httpx.Request) -> httpx.Response:
+        path = request.url.path
+        if path == "/v1/trial/register":
+            return self._register(request)
+        install_id = request.headers.get("X-Affix-Install-Id")
+        subject = self.installs.get(install_id or "")
+        if subject is None:
+            return httpx.Response(403, json={"error": "install_rejected"})
+        used = self.subject_used.get(subject, 0)
+        remaining = max(0, self.limit - used)
+        headers = {
+            "X-Affix-Trial-Limit": str(self.limit),
+            "X-Affix-Trial-Used": str(used),
+            "X-Affix-Trial-Remaining": str(remaining),
+        }
+        if path.endswith("/prove"):
+            if remaining <= 0:
+                return httpx.Response(
+                    403,
+                    json={
+                        "error": "trial_exhausted",
+                        "reason_code": "TRIAL_EXHAUSTED",
+                        "message": "Trial allowance used up",
+                        "limit": self.limit,
+                        "used": used,
+                    },
+                    headers=headers,
+                )
+            self.subject_used[subject] = used + 1
+            return httpx.Response(200, json={"proof": "proof_hex"}, headers=headers)
+        if path == "/v1/gate/verify":
+            return httpx.Response(
+                200,
+                json={"allow": True, "reason_code": "ADMITTED", "mode": "consume"},
+                headers=headers,
+            )
+        if path == "/api/attest":
+            return httpx.Response(200, json={"attestation": {"algorithm": "ML-DSA-65"}})
+        if path == "/v1/trial/quota":
+            return httpx.Response(
+                200,
+                json={"limit": self.limit, "used": used, "remaining": remaining},
+                headers=headers,
+            )
+        return httpx.Response(200, json={"ok": True}, headers=headers)
+
+    def _register(self, request: httpx.Request) -> httpx.Response:
+        import json as jsonlib
+
+        body = jsonlib.loads(request.content.decode("utf-8"))
+        subject = str(body["subject"])
+        self.registrations += 1
+        self.install_counter += 1
+        install_id = f"ins_{self.install_counter}"
+        self.installs[install_id] = subject
+        used = self.subject_used.setdefault(subject, 0)
+        return httpx.Response(
+            201,
+            json={
+                "install_id": install_id,
+                "install_secret": "secret-value",
+                "subject_id": subject,
+                "product": "huggingface",
+                "quota": {
+                    "limit": self.limit,
+                    "used": used,
+                    "remaining": max(0, self.limit - used),
+                },
+            },
+        )
+
+
+@pytest.fixture()
+def cache_file(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
+    path = tmp_path / "install.json"
+    monkeypatch.setenv("AFFIX_INSTALL_FILE", str(path))
+    monkeypatch.setenv("AFFIX_TRIAL_SUBJECT", "tester@example.com")
+    monkeypatch.setenv("HF_TOKEN", "hf_test_token")
+    return path
+
+
+def build_client(server: FakeQuotaServer) -> tuple[AffixHuggingFace, FakeHfClient]:
+    http = httpx.Client(transport=httpx.MockTransport(server.handler))
+    transport = AffixTransport("aio_public_trial", client=http)
+    hf = FakeHfClient()
+    client = AffixHuggingFace(
+        affix_transport=transport,
+        hf_client=hf,
+        trial=True,
+        evidence_mode="off",
+    )
+    return client, hf
+
+
+def test_first_use_registers_and_caches(cache_file: Path) -> None:
+    server = FakeQuotaServer()
+    client, _ = build_client(server)
+
+    client.text_generation("prompt", model=ModelRef("org/model"), checks=PASSING_CHECKS)
+
+    assert server.registrations == 1
+    assert cache_file.exists()
+    cached = load_credentials(cache_file)
+    assert cached is not None
+    assert cached.install_id == "ins_1"
+
+
+def test_cached_install_is_reused(cache_file: Path) -> None:
+    server = FakeQuotaServer()
+    client, _ = build_client(server)
+
+    client.text_generation("one", model=ModelRef("org/model"), checks=PASSING_CHECKS)
+    client.text_generation("two", model=ModelRef("org/model"), checks=PASSING_CHECKS)
+
+    assert server.registrations == 1
+    assert server.subject_used[subject_digest("tester@example.com")] == 2
+
+
+def test_deleting_the_cache_does_not_restore_proofs(cache_file: Path) -> None:
+    server = FakeQuotaServer(limit=3)
+    client, _ = build_client(server)
+    for _ in range(3):
+        client.text_generation("prompt", model=ModelRef("org/model"), checks=PASSING_CHECKS)
+
+    # Simulate uninstall: local credentials are gone.
+    cache_file.unlink()
+    assert load_credentials(cache_file) is None
+
+    fresh_client, fresh_hf = build_client(server)
+    with pytest.raises(TrialExhausted) as exc:
+        fresh_client.text_generation("prompt", model=ModelRef("org/model"), checks=PASSING_CHECKS)
+
+    assert server.registrations == 2
+    assert exc.value.limit == 3
+    assert fresh_hf.calls == []
+
+
+def test_exhaustion_blocks_hugging_face(cache_file: Path) -> None:
+    server = FakeQuotaServer(limit=2)
+    client, hf = build_client(server)
+    client.text_generation("one", model=ModelRef("org/model"), checks=PASSING_CHECKS)
+    client.text_generation("two", model=ModelRef("org/model"), checks=PASSING_CHECKS)
+    assert len(hf.calls) == 2
+
+    with pytest.raises(TrialExhausted):
+        client.text_generation("three", model=ModelRef("org/model"), checks=PASSING_CHECKS)
+    assert len(hf.calls) == 2
+
+
+def test_pre_issued_proof_still_reports_quota(cache_file: Path) -> None:
+    server = FakeQuotaServer()
+    client, _ = build_client(server)
+    client.chat_completion(
+        [{"role": "user", "content": "hello"}],
+        model=ModelRef("org/model"),
+        proof=AdmissionProof("proof_hex"),
+    )
+    quota = client.quota
+    assert quota is not None
+    assert quota.limit == 100
+    assert quota.remaining == 100
+
+
+def test_refresh_quota_reads_server_state(cache_file: Path) -> None:
+    server = FakeQuotaServer(limit=10)
+    client, _ = build_client(server)
+    client.text_generation("one", model=ModelRef("org/model"), checks=PASSING_CHECKS)
+
+    quota = client.refresh_quota()
+    assert quota.used == 1
+    assert quota.remaining == 9
+
+
+def test_install_headers_are_sent(cache_file: Path) -> None:
+    seen: list[httpx.Request] = []
+    server = FakeQuotaServer()
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen.append(request)
+        return server.handler(request)
+
+    http = httpx.Client(transport=httpx.MockTransport(handler))
+    transport = AffixTransport("aio_public_trial", client=http)
+    client = AffixHuggingFace(
+        affix_transport=transport,
+        hf_client=FakeHfClient(),
+        trial=True,
+        evidence_mode="off",
+    )
+    client.text_generation("prompt", model=ModelRef("org/model"), checks=PASSING_CHECKS)
+
+    prove = next(r for r in seen if r.url.path.endswith("/prove"))
+    assert prove.headers["X-Affix-Install-Id"] == "ins_1"
+    assert prove.headers["X-Affix-Install-Secret"] == "secret-value"
+
+
+def test_registration_throttle_surfaces_clearly(cache_file: Path) -> None:
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(
+            429,
+            json={
+                "error": "registration_throttled",
+                "message": "Too many new trial subjects from this origin today.",
+            },
+        )
+
+    http = httpx.Client(transport=httpx.MockTransport(handler))
+    transport = AffixTransport("aio_public_trial", client=http, max_retries=0)
+    client = AffixHuggingFace(
+        affix_transport=transport,
+        hf_client=FakeHfClient(),
+        trial=True,
+        evidence_mode="off",
+    )
+    with pytest.raises(RegistrationThrottled):
+        client.text_generation("prompt", model=ModelRef("org/model"), checks=PASSING_CHECKS)
+
+
+def test_subject_resolution_is_stable_and_opaque() -> None:
+    first = resolve_subject(subject="Tester@Example.com")
+    second = resolve_subject(subject="  tester@example.com  ")
+    assert first == second
+    assert "tester" not in first
+    assert len(first) == 64
+
+
+def test_subject_resolution_fails_closed(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv("AFFIX_TRIAL_SUBJECT", raising=False)
+    monkeypatch.delenv("HF_TOKEN", raising=False)
+    with pytest.raises(ConfigurationError):
+        resolve_subject()
+
+
+def test_credentials_round_trip(tmp_path: Path) -> None:
+    path = tmp_path / "install.json"
+    credentials = TrialCredentials(
+        install_id="ins_x",
+        install_secret="s",
+        subject_id="d" * 64,
+    )
+    save_credentials(credentials, path)
+    assert load_credentials(path) == credentials
+    assert path.stat().st_mode & 0o777 == 0o600
+
+
+def test_own_api_key_disables_trial(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("HF_TOKEN", "hf_test_token")
+    server = FakeQuotaServer()
+    http = httpx.Client(transport=httpx.MockTransport(server.handler))
+    transport = AffixTransport("aio_customer_key", client=http)
+    client = AffixHuggingFace(
+        affix_api_key="aio_customer_key",
+        affix_transport=transport,
+        hf_client=FakeHfClient(),
+        evidence_mode="off",
+    )
+    assert client._trial is False
+
+
+def test_public_trial_key_used_when_none_supplied(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.delenv("AFFIX_API_KEY", raising=False)
+    monkeypatch.setenv("HF_TOKEN", "hf_test_token")
+    captured: dict[str, Any] = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        captured["auth"] = request.headers.get("X-API-Key")
+        return httpx.Response(200, json={"ok": True})
+
+    http = httpx.Client(transport=httpx.MockTransport(handler))
+    client = AffixHuggingFace(hf_client=FakeHfClient(), trial=False)
+    client._affix.close()
+    client._affix = AffixTransport(client._affix.api_key, client=http)
+    client.health()
+    assert captured["auth"].startswith("aio_")