actproof 0.2.0__tar.gz → 0.3.0__tar.gz

{actproof-0.2.0 → actproof-0.3.0}/CHANGELOG.md

@@ -12,18 +12,65 @@ release. Once 1.0.0 ships, semantic versioning will be strictly followed.
 
 ### Planned
 
-- **v0.2.0** — `docs/` complete with three worked examples (NIS2 / EUDR / software release), GitHub Action wrapper `release-anchor.yml`, EU Trusted List chain validation for RFC 3161 tokens, stricter verifier semantics (PARTIAL state distinct from PASS), disclosure CLI subcommands (`actproof verify-disclosure`, `actproof issue-disclosure`).
-- **v0.3.0** — Cross-implementation conformance test suite landing.
+- **v0.4.0** — Pluggable anchor backend architecture. Generalize the chain-agnostic substrate (canonicalization, RFC 3161 timestamps, receipt format, verifier) into an `AnchorBackend` protocol with chain-specific implementations (Hedera Consensus Service, Stellar memo-hash, Bitcoin OP_RETURN, Ethereum). See `docs/ANCHOR_BACKENDS.md` for the design intent.
 - **v1.0.0** — API frozen.
 - **v2.0.0** — COSE_Sign1 + SCITT Transparent Statement bridge, once RFC 9943 publishes.
 
+## [0.3.0] — 2026-05-17
+
+**Security hardening release.** Closes a transaction-validation gap present in v0.2.0. See `SECURITY.md` for the advisory.
+
+### Security
+
+- **`AlgorandSigner.validate_transaction` now rejects attack-vector fields unconditionally.** `rekey_to`, `close_remainder_to`, `group`, and `lease` are rejected on every transaction. v0.2.0 accepted these fields if the sender, receiver, amount, and note prefix passed validation; a `rekey_to=attacker` payment was therefore accepted as a benign-looking 0-ALGO self-payment. This is the same attack class that drained roughly 3.3 million USD across 25 accounts in the February 2023 MyAlgo wallet incident.
+- **Transaction type restricted to `PaymentTxn`.** v0.2.0 accepted any `algosdk.transaction.Transaction` subclass. v0.3.0 rejects `AssetTransferTxn`, `ApplicationCallTxn`, `KeyregTxn`, and any other non-payment type.
+- **Fee bounded and forced flat.** `txn.fee` must lie in `[ALGORAND_MIN_FEE_MICROALGOS, max_fee_microalgos]` (default 1000 microALGOs). `build_transaction` now forces `flat_fee=True` and `fee=1000` on the copy of `SuggestedParams` it passes to `PaymentTxn`, so per-byte fee rates returned by algod under congestion do not produce a transaction the signer would reject.
+- **Note size bounded.** New constant `ALGORAND_MAX_NOTE_BYTES = 1024` enforced explicitly by the signer before any KMS call.
+- **`GoogleKMSSigner`: fail-closed end-to-end integrity verification.** Every KMS call now requires `response.name == request.name`, `response.verified_data_crc32c is True`, `crc32c(signature) == response.signature_crc32c`, and `len(signature) == 64`. Same pattern for `get_public_key` (`response.name`, `pem_crc32c`). v0.2.0 used `hasattr(...)` guards that silently bypassed missing fields; v0.3.0 raises `RuntimeError` if any required field is missing or invalid. Implementation follows Google's recommended pattern documented at `cloud.google.com/kms/docs/data-integrity-guidelines`.
+- **`_assemble_signed_transaction` validates signature length.** Refuses to wrap a non-64-byte signature into a `SignedTransaction` (Ed25519 signatures are always 64 octets per RFC 8032).
+- **Release workflow now runs the test suite before publishing.** `.github/workflows/release.yml` adds a pytest gate plus wheel smoke-test job that the publish job depends on. A failing test now blocks the PyPI upload.
+
+### Changed
+
+- **`AlgorandSigner.__init__` accepts `allowed_note_prefixes` and `max_fee_microalgos` only.** The earlier v0.3.0 draft had also exposed `require_self_payment` and `require_zero_amount` as configurable booleans; these were removed because disabling them turned the signer into a general-purpose Algorand signing adapter, broader than its stated scope. The strict 0-ALGO self-payment shape is now a non-configurable invariant.
+- **`allowed_note_prefixes` accepts a single `bytes` value.** Passing `allowed_note_prefixes=b"quoruna/v1:"` now works without wrapping in a list. The constructor also raises a clearer `TypeError` when a non-bytes element is found.
+- **`__init_subclass__` walks the full MRO.** Forbidden method names inherited via mixin (`class BadSigner(RawSigningMixin, AlgorandSigner)`) are now caught at class-definition time, not only methods defined directly on the subclass.
+- **`validate_transaction` fails closed on missing `super().__init__()`.** Earlier drafts silently set defaults if a subclass forgot to call the base init. v0.3.0 raises `RuntimeError` listing every missing policy attribute.
+- **GCP KMS protection level wording.** Module and class docstrings no longer claim "HSM-backed" unconditionally. The signer accepts keys with any protection level (`SOFTWARE`, `HSM`, `HSM_SINGLE_TENANT`, `EXTERNAL`); operators who need HSM-residency guarantees should create the key version accordingly.
+- **`GoogleKMSSigner` without `[gcp]` deps.** Previously `actproof.signers.GoogleKMSSigner` was set to `None` if the GCP optional dependencies were missing, producing a confusing `TypeError: 'NoneType' object is not callable` on instantiation. v0.3.0 substitutes a stub subclass that raises a clear `RuntimeError` with the install command.
+- **`tsp-client` dependency loosened to `>=0.2.1,<0.3`.** Downstream applications that pull a slightly newer compatible patch release are no longer blocked by the exact-pin requirement.
+
+### Added
+
+- `ALGORAND_MIN_FEE_MICROALGOS`, `ALGORAND_DEFAULT_MAX_FEE_MICROALGOS`, `ALGORAND_MAX_NOTE_BYTES` constants on `actproof.signers.interface`.
+- New test module `tests/test_signers_v030_policy.py` with 52 tests covering the rejection paths above plus KMS response-verification fail-closed semantics. Includes a cryptographic-equivalence regression test that confirms v0.3.0 produces byte-identical signatures to v0.2.0 for the original strict-policy use case.
+- Two new tests in `tests/test_anchor.py` for `build_transaction`: confirms the resulting transaction carries `fee=1000` regardless of caller-supplied fee rate, and confirms the caller's `SuggestedParams` object is not mutated.
+- `SECURITY.md` documenting the v0.2.0 gap, the v0.3.0 fix, and the threat model. Now included in the sdist.
+- `docs/ANCHOR_BACKENDS.md` design note for v0.4.0 multi-chain anchor abstraction.
+- `docs/INTEGRATION.md` integration guide for downstream applications consuming actproof.
+- `actproof/py.typed` PEP 561 marker so downstream type-checkers honor inline annotations.
+
+### Migration from v0.2.0
+
+Existing callers using the strict actproof policy (default constructors, anchoring with `actproof:j{...}` notes, 0-ALGO self-payments, fee 1000) see no behavioural change: the signed bytes are byte-identical. Previously-accepted transactions carrying `rekey_to`, `close_remainder_to`, `group`, `lease`, fees above 1000 microALGOs, or notes longer than 1024 bytes are now rejected with `SignerValidationError`. Audit your transaction-construction code to confirm none of these fields should have been set; for a higher `fee` ceiling during network congestion, pass `max_fee_microalgos=<n>` to the signer constructor.
+
+Callers of any earlier v0.3.0 draft that used `require_self_payment=False` or `require_zero_amount=False` need to refactor: those kwargs were removed. If you need to sign other transaction shapes, write your own `AlgorandSigner` subclass and override `validate_transaction`.
+
+### Acknowledgements
+
+Independent review by ChatGPT (May 2026, three review rounds) flagged the original `rekey_to`/`close_remainder_to` gap, the KMS integrity-check weakening, the MRO walk gap, the configurable-policy footgun, the test-gating mistake, the flat-fee deployment issue, the release-workflow missing test gate, and seven additional release-quality items. All findings are addressed in this release.
+
 ## [0.2.0] — 2026-05-17
 
+Version bump for the initial PyPI publication path. See [0.1.0] notes below for the substrate API description; v0.2.0 was the version that actually shipped to PyPI (the 0.1.0 slot was skipped per immutable-release policy).
+
+## [0.1.0] — 2026-05-17
+
 **First PyPI release of `actproof`.** This is the inaugural published version of the substrate library under its canonical name. The library is installable via `pip install actproof`.
 
 ### Project history
 
-The code in this release was developed under the working name `openproof` on GitHub. The repository at `github.com/deyan-paroushev/openproof-py` was renamed to `github.com/deyan-paroushev/actproof-py` on 2026-05-17; the old URL auto-redirects to the new one. GitHub tags `v0.1.0` (initial public-API surface) and `v0.1.1` (additive schema v3 support) under the previous repository name are the development history of this code; this `v0.2.0` on PyPI is the first published release under the canonical name and supersedes both working-name tags.
+The code in this release was developed under the working name `openproof` on GitHub. The repository at `github.com/deyan-paroushev/openproof-py` was renamed to `github.com/deyan-paroushev/actproof-py` on 2026-05-17; the old URL auto-redirects to the new one. GitHub tags `v0.1.0` (initial public-API surface) and `v0.1.1` (additive schema v3 support) under the previous repository name are the development history of this code; this `v0.1.0` on PyPI is the first published release under the canonical name and supersedes both working-name tags.
 
 The PyPI namespace under `openproof` is unrelated to this project.
 

actproof-0.3.0/DEPLOY.md

@@ -0,0 +1,120 @@
+# Deployment
+
+This is the actproof-py v0.1.0 source tree, ready to push to
+`github.com/deyan-paroushev/actproof-py`.
+
+## What's inside
+
+```
+actproof-py/
+├── README.md                       Project README
+├── CHANGELOG.md                    Full v0.0.1 → v0.1.0 history
+├── LICENSE                         MIT
+├── DEPLOY.md                       This file
+├── pyproject.toml                  Hatchling build, dependencies pinned
+├── .gitignore
+├── actproof/                      Library source (~3,500 lines, 10 modules)
+│   ├── __init__.py
+│   ├── canonical.py                RFC 8785 JCS, strict-mode discipline
+│   ├── manifest.py                 Manifest envelope (issuer/claim/evidence/recipients)
+│   ├── catalogue.py                actproof-events loader + validator
+│   ├── receipt.py                  Public Receipt + private IssuerEvidence
+│   ├── timestamp.py                RFC 3161 with QTSP failover chain
+│   ├── anchor.py                   ARC-2 disclosed-mode notes on Algorand
+│   ├── signers/                    AlgorandSigner ABC + Mnemonic + GoogleKMS
+│   ├── verify.py                   Six-check end-to-end verification
+│   └── cli.py                      Click-based CLI (anchor / verify / validate)
+├── tests/                          11 test files, 443 tests, all passing
+│   └── ...
+└── docs/
+    └── STS-STANDARDS-APPLICATION.md   Maintainer application narrative
+```
+
+## First push to GitHub
+
+```bash
+cd actproof-py
+
+git init
+git add -A
+git commit -m "Initial release: actproof-py v0.1.0
+
+Library and CLI for anchoring signed JSON manifests to Algorand mainnet
+with RFC 3161 qualified timestamps, plus an independent verifier for
+anyone's anchored receipts.
+
+10 modules, 443 passing tests, MIT licensed.
+
+Implements RFC 8785 JCS, RFC 3161 TSP, Algorand ARC-2 disclosed-mode
+notes, and tracks draft-ietf-scitt-architecture for the v2 COSE_Sign1
+bridge once RFC 9943 publishes."
+
+git branch -M main
+git remote add origin git@github.com:deyan-paroushev/actproof-py.git
+git push -u origin main
+
+git tag -a v0.1.0 -m "v0.1.0: first usable release"
+git push origin v0.1.0
+```
+
+## Local verification
+
+```bash
+python -m venv .venv
+. .venv/bin/activate
+pip install -e ".[dev,gcp]"
+
+# Sanity checks
+actproof --version              # actproof, version 0.1.0
+python -c "import actproof; print(actproof.__version__)"
+
+# Full test suite — expect 443 passed (with ACTPROOF_EVENTS_ROOT set, see Notes below)
+ACTPROOF_EVENTS_ROOT=/path/to/actproof-events python -m pytest tests/ -q
+
+# CLI help
+actproof --help
+actproof anchor --help
+actproof verify --help
+actproof validate --help
+```
+
+## Notes for the catalogue
+
+Several tests and the `actproof validate` command need the
+actproof-events catalogue to be present somewhere resolvable.
+
+The library (CLI flag, env var, error):
+
+1. The `--catalogue` CLI flag (a path to the `acts/` directory)
+2. The `ACTPROOF_CATALOGUE_PATH` environment variable
+3. Otherwise raises `CatalogueLoadError`
+
+The test suite (env var, sibling repo, skip):
+
+1. The `ACTPROOF_EVENTS_ROOT` environment variable (a path to the
+   actproof-events repo root, not the `acts/` directory)
+2. Falls back to `../actproof-events` as a sibling of this repo
+3. Tests that need the real catalogue skip cleanly if neither is
+   available; tests using synthetic `tmp_path` catalogues run regardless
+
+For local development against `github.com/deyan-paroushev/actproof-events`:
+
+```bash
+# Clone as a sibling of this repo
+git clone https://github.com/deyan-paroushev/actproof-events.git ../actproof-events
+
+# Or set the env vars explicitly
+export ACTPROOF_EVENTS_ROOT=/path/to/actproof-events                  # tests
+export ACTPROOF_CATALOGUE_PATH=$ACTPROOF_EVENTS_ROOT/catalogue/acts   # library/CLI
+```
+
+## STS Standards Network application
+
+The maintainer's statement of practice is at
+`docs/STS-STANDARDS-APPLICATION.md`. It is written against the four
+sections of the Sovereign Tech Standards Network application form
+(maintainer profile, standards relation, twelve-month plan, track
+record) plus a conflicts-and-disclosures appendix.
+
+It is structured to be read by the application reviewer; nothing in it
+is load-bearing for the library itself.

{actproof-0.2.0 → actproof-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: actproof
-Version: 0.2.0
+Version: 0.3.0
 Summary: Verifiable receipts of regulated acts. Canonical JSON (RFC 8785), RFC 3161 trusted timestamps, Algorand ARC-2 anchoring, independent verification.
 Project-URL: Homepage, https://github.com/deyan-paroushev/actproof-py
 Project-URL: Documentation, https://github.com/deyan-paroushev/actproof-py/tree/main/docs
@@ -54,7 +54,7 @@ Requires-Dist: cryptography<46.0,>=42.0
 Requires-Dist: py-algorand-sdk<3.0,>=2.6.1
 Requires-Dist: requests<3.0,>=2.32.0
 Requires-Dist: rfc8785<0.2,>=0.1.4
-Requires-Dist: tsp-client==0.2.1
+Requires-Dist: tsp-client<0.3,>=0.2.1
 Provides-Extra: dev
 Requires-Dist: mypy>=1.10; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'

actproof-0.3.0/SECURITY.md

@@ -0,0 +1,90 @@
+# Security advisory: actproof v0.2.0
+
+## Summary
+
+actproof v0.2.0 (released to PyPI on 17 May 2026) contains a
+transaction-validation gap in `actproof.signers.AlgorandSigner.validate_transaction`.
+The signer accepts Algorand transactions that carry `rekey_to`,
+`close_remainder_to`, arbitrary `fee`, `group`, or `lease` fields, as
+long as the sender, receiver, amount, and note prefix pass validation.
+
+An attacker who can construct an `algosdk.transaction.Transaction` and
+pass it to `sign_transaction` can therefore have the signer authorise a
+transaction that looks like a benign 0-ALGO self-payment but actually
+transfers signing authority of the account to an address the attacker
+controls (`rekey_to`), drains the account's remaining balance
+(`close_remainder_to`), or burns ALGO via an inflated `fee`.
+
+The Algorand `rekey_to` field is the same attack class that drained
+roughly 3.3 million USD across approximately 25 accounts in the
+February 2023 MyAlgo wallet incident.
+
+## Severity
+
+High. Exploitation requires the attacker to have the ability to
+construct and submit a transaction to the signer (i.e. application-
+layer compromise above the signer). The KMS key itself remains
+protected by the HSM. However, the signer is the trust boundary the
+package advertises, so the gap weakens the security guarantee the
+package was meant to provide.
+
+## Affected versions
+
+- `actproof` 0.2.0 (the only public release as of this advisory)
+
+## Fixed in
+
+- `actproof` 0.3.0
+
+## Mitigation if upgrading is not immediate
+
+Audit all call sites that pass a `Transaction` object to
+`AlgorandSigner.sign_transaction`. Verify that every `Transaction`
+passed is constructed by code you control and that no path constructs
+a `Transaction` with `rekey_to`, `close_remainder_to`, `group`, or
+`lease` set.
+
+## Fix in v0.3.0
+
+`validate_transaction` now rejects:
+
+1. Any transaction that is not a `PaymentTxn` (rejects
+   `AssetTransferTxn`, `ApplicationCallTxn`, `KeyregTxn`, and other
+   transaction classes).
+2. Any transaction with `rekey_to` set.
+3. Any transaction with `close_remainder_to` set.
+4. Any transaction with `group` set.
+5. Any transaction with `lease` set.
+6. Any transaction with `fee` outside
+   `[ALGORAND_MIN_FEE_MICROALGOS, max_fee_microalgos]` (default range:
+   exactly 1000 microALGO).
+
+The two booleans `require_self_payment` and `require_zero_amount`
+that earlier drafts of v0.3.0 added as configurable kwargs were
+removed. The strict actproof anchoring shape (0-ALGO self-payment,
+tagged note, no rekey/close/group/lease) is now non-configurable.
+
+The only remaining configurable policy parameters are
+`allowed_note_prefixes` (the legitimate point of variation between
+actproof, Quoruna, and other downstream anchoring schemes) and
+`max_fee_microalgos` (so callers can anchor during network congestion
+with an explicit, auditable decision).
+
+## GCP KMS hardening
+
+In addition to the transaction-policy fix, v0.3.0 implements Google's
+recommended end-to-end integrity verification pattern for KMS
+responses, fail-closed on every check. See
+`actproof/signers/google_kms.py` and the v0.3.0 changelog entry.
+
+## Acknowledgements
+
+Independent review by ChatGPT (May 2026) flagged the
+`rekey_to`/`close_remainder_to` gap and the KMS integrity-check
+weakening. Both findings are addressed in v0.3.0.
+
+## Contact
+
+For security questions, open a GitHub issue at
+https://github.com/deyan-paroushev/actproof-py or email the address
+in `pyproject.toml`.

{actproof-0.2.0 → actproof-0.3.0}/actproof/__init__.py

@@ -6,7 +6,7 @@ actproof: anchor signed JSON manifests; verify anyone's anchored receipts.
 
 from __future__ import annotations
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"
 
 
 # ─────────────────────────────────────────────────────────────────

{actproof-0.2.0 → actproof-0.3.0}/actproof/anchor.py

@@ -78,6 +78,7 @@ API
 from __future__ import annotations
 
 import base64
+import copy
 import logging
 import time
 from dataclasses import dataclass
@@ -95,6 +96,7 @@ from actproof.receipt import (
     ARC2_NOTE_FORMAT,
     AnchorRecord,
 )
+from actproof.signers.interface import ALGORAND_MIN_FEE_MICROALGOS
 
 
 logger = logging.getLogger(__name__)
@@ -341,9 +343,24 @@ def build_transaction(
     """
     _ensure_algosdk()
     note = build_note_bytes(manifest_hash, batching_profile)
+
+    # Force the anchoring transaction to use a flat minimum fee.
+    # ChatGPT v0.3.0 review Finding 2: without this, algod's
+    # suggested_params can carry flat_fee=False and a per-byte fee
+    # rate. The SDK then computes a transaction fee as
+    # fee_per_byte * tx_size, which for a ~400-byte anchoring
+    # transaction at moderate congestion easily exceeds the signer's
+    # max_fee_microalgos cap (default 1000) and would be rejected at
+    # validation time. We mutate a copy of the params so callers who
+    # supplied their own SuggestedParams object are not surprised by
+    # in-place changes.
+    sp = copy.copy(suggested_params)
+    sp.flat_fee = True
+    sp.fee = ALGORAND_MIN_FEE_MICROALGOS
+
     return PaymentTxn(
         sender=signer_address,
-        sp=suggested_params,
+        sp=sp,
         receiver=signer_address,
         amt=0,
         note=note,

actproof-0.3.0/actproof/signers/__init__.py

@@ -0,0 +1,139 @@
+# SPDX-FileCopyrightText: 2026 Deyan Paroushev
+# SPDX-License-Identifier: MIT
+"""
+Signer implementations for actproof anchoring.
+
+A signer holds an Algorand Ed25519 private key (or a reference to one
+in external custody) and signs transactions built by
+``actproof.anchor``. Every concrete signer subclasses
+``AlgorandSigner`` so the contract ("transactions only, never raw
+bytes") is structurally enforced.
+
+What's in this package
+----------------------
+
+* ``AlgorandSigner`` (in ``interface.py``) - the abstract base class.
+  Concrete signers MUST subclass it. ``__init_subclass__`` raises
+  ``TypeError`` if a subclass exposes any method whose name suggests
+  raw-byte signing, whether defined directly or inherited via a
+  mixin (the full forbidden-name list is the module constant
+  ``FORBIDDEN_METHOD_NAMES``).
+
+* ``MnemonicSigner`` (in ``mnemonic.py``) - holds an Algorand
+  mnemonic in process memory and signs locally. **Testing only.**
+  Emits a loud ``UserWarning`` on construction. Production keys
+  belong in an HSM-grade KMS.
+
+* ``GoogleKMSSigner`` (in ``google_kms.py``) - production-grade
+  signer for users who hold their Ed25519 key in Google Cloud KMS.
+  KMS supports Ed25519 natively via the ``EC_SIGN_ED25519``
+  algorithm; the private key never leaves the KMS service. For
+  HSM-residency guarantees, use a key with protection level ``HSM``
+  or ``HSM_SINGLE_TENANT``. Requires the optional ``[gcp]`` install
+  extra (``pip install 'actproof[gcp]'``).
+
+What's NOT in this package
+--------------------------
+
+AWS KMS does not support Ed25519 directly (only RSA and SEC ECC
+curves P-256/P-384/P-521 plus secp256k1). AWS users with HSM-grade
+requirements need either AWS CloudHSM (where Ed25519 is supported)
+or an envelope-encryption pattern. Either path is out-of-scope here;
+AWS users implement their own ``AlgorandSigner`` subclass against
+their preferred backend.
+
+Azure Key Vault and HashiCorp Vault similarly: write your own
+subclass against their SDKs. The ABC's enforcement does the security
+work regardless of backend.
+
+Example
+-------
+
+::
+
+    from actproof.signers import MnemonicSigner
+    from actproof import anchor_manifest, AnchorMode
+
+    signer = MnemonicSigner("...25 words separated by spaces...")
+    record = anchor_manifest(
+        manifest_hash,
+        signer=signer,
+        mode=AnchorMode.DEMO,  # testnet
+    )
+
+For production with GCP KMS::
+
+    from actproof.signers import GoogleKMSSigner
+
+    signer = GoogleKMSSigner(
+        kms_resource_name=(
+            "projects/my-project/locations/europe-west4/"
+            "keyRings/anchoring/cryptoKeys/anchor-signer-v1/"
+            "cryptoKeyVersions/1"
+        ),
+    )
+"""
+
+from __future__ import annotations
+
+from actproof.signers.interface import (
+    ALGORAND_DEFAULT_MAX_FEE_MICROALGOS,
+    ALGORAND_MAX_NOTE_BYTES,
+    ALGORAND_MIN_FEE_MICROALGOS,
+    FORBIDDEN_METHOD_NAMES,
+    AlgorandSigner,
+    SignerValidationError,
+)
+from actproof.signers.mnemonic import MnemonicSigner
+
+# Optional: GoogleKMSSigner requires google-cloud-kms. Import is
+# best-effort; if the GCP libraries are not installed, expose a stub
+# class that raises a clear RuntimeError on instantiation rather than
+# silently substituting None. ChatGPT v0.3.0 review Finding 5: the
+# previous None fallback caused
+# ``TypeError: 'NoneType' object is not callable`` for library users,
+# which is poor UX.
+try:
+    from actproof.signers.google_kms import GoogleKMSSigner
+    _GOOGLE_KMS_AVAILABLE: bool = True
+    _GOOGLE_KMS_ERROR: str | None = None
+except Exception as exc:  # noqa: BLE001
+    _GOOGLE_KMS_AVAILABLE = False
+    _GOOGLE_KMS_ERROR = str(exc)
+
+    class GoogleKMSSigner(AlgorandSigner):  # type: ignore[no-redef]
+        """Stub raised when ``actproof[gcp]`` is not installed.
+
+        Instantiating this stub fails fast with a clear installation
+        hint. The real ``GoogleKMSSigner`` is imported from
+        ``actproof.signers.google_kms`` when the optional dependencies
+        are present.
+        """
+
+        def __init__(self, *args: object, **kwargs: object) -> None:
+            raise RuntimeError(
+                "GoogleKMSSigner requires the optional GCP "
+                "dependencies (google-cloud-kms, google-crc32c, "
+                "cryptography). Install them with:\n\n"
+                "    pip install 'actproof[gcp]'\n\n"
+                f"Underlying import error: {_GOOGLE_KMS_ERROR}"
+            )
+
+        @property
+        def address(self) -> str:  # pragma: no cover
+            raise RuntimeError("GoogleKMSSigner stub has no address.")
+
+        def sign_transaction(self, txn: object) -> object:  # pragma: no cover
+            raise RuntimeError("GoogleKMSSigner stub cannot sign.")
+
+
+__all__ = [
+    "AlgorandSigner",
+    "MnemonicSigner",
+    "GoogleKMSSigner",
+    "FORBIDDEN_METHOD_NAMES",
+    "SignerValidationError",
+    "ALGORAND_MIN_FEE_MICROALGOS",
+    "ALGORAND_DEFAULT_MAX_FEE_MICROALGOS",
+    "ALGORAND_MAX_NOTE_BYTES",
+]