fix: guard CAP-71 delegate signing against expiration mismatch

Author: overcat

CHANGELOG.md

@@ -3,6 +3,12 @@ Release History
 
 ### Pending
 
+#### Fixes
+- `auth.authorize_entry` no longer re-stamps an authorization entry's expiration ledger out from under a signature the entry already carries. A CAP-71-01 (`SOROBAN_CREDENTIALS_ADDRESS_WITH_DELEGATES`) entry has one `signature_expiration_ledger`, shared by the top-level address and every (nested) delegate, and each of their signatures commits to it — so signing one node with a `valid_until_ledger_sequence` different from the one already stored left the earlier signatures in place but no longer verifiable, and nothing was raised until the host rejected the entry. ([#1215](https://github.com/StellarCN/py-stellar-base/issues/1215))
+  - `authorize_entry` now resolves the target node(s) before touching the entry and raises `ValueError`, naming the stored expiration ledger, when the requested one would invalidate a signature on any node outside them. Signature values are opaque to the SDK, so every value other than `scvVoid` counts, `scvVoid` being the marker for a node still awaiting one — the convention `build_with_delegates_entry` and `needs_non_invoker_signing_by` already follow. An account contract that accepts `scvVoid` itself as a valid signature is therefore not covered. Re-signing the targeted node(s) with a new expiration is still allowed, and `ADDRESS` / `ADDRESS_V2` entries — which carry a single node — are unaffected.
+  - `AssembledTransaction[Async].authorize` / `sign_auth_entries` reach the same guard. They can only sign a delegates entry's top-level node, but the expiration they stamp (`latest_ledger + 100` by default) is the shared one, so signing the top level of an entry whose delegates have already signed now raises instead of invalidating them; pass those delegates' `valid_until_ledger_sequence` explicitly.
+  - `build_with_delegates_entry` documents that a signature already present on the wrapped entry is not carried over, which was true but undocumented.
+
 ### Version 16.1.0
 
 Released on September 02, 2026

stellar_sdk/auth.py

@@ -107,6 +107,35 @@ def walk(delegates: list[stellar_xdr.SorobanDelegateSignature]) -> None:
     return nodes
 
 
+def _has_signed_node_outside(
+    credentials: stellar_xdr.SorobanCredentials,
+    targets: Sequence[
+        stellar_xdr.SorobanAddressCredentials | stellar_xdr.SorobanDelegateSignature
+    ],
+) -> bool:
+    """Whether a signature-carrying node other than ``targets`` is already signed.
+
+    The entry has a single, shared ``signature_expiration_ledger``, and a
+    signature over the payload it belongs to stops verifying if that field
+    changes. Nodes are matched by identity, so the exclusion covers exactly the
+    nodes about to be replaced.
+
+    A signature ``SCVal`` is opaque to the SDK, so this conservatively treats
+    every non-``scvVoid`` value as payload-bound. ``scvVoid`` marks a node still
+    awaiting a signature — the convention the rest of the SDK already follows,
+    in :func:`build_with_delegates_entry` and in
+    ``AssembledTransaction.needs_non_invoker_signing_by`` — which means an
+    account contract that accepts ``scvVoid`` itself as a valid signature is not
+    covered here.
+    """
+    target_ids = {id(node) for node in targets}
+    return any(
+        id(node) not in target_ids
+        and node.signature.type != stellar_xdr.SCValType.SCV_VOID
+        for node in _collect_signature_nodes(credentials)
+    )
+
+
 def build_authorization_preimage(
     entry: stellar_xdr.SorobanAuthorizationEntry,
     valid_until_ledger_sequence: int,
@@ -254,8 +283,14 @@ def authorize_entry(
     The signed payload commits to ``valid_until_ledger_sequence``, and for a
     delegates entry the top-level account and every (nested) delegate sign the
     same payload — so every signer of one entry must use the same
-    ``valid_until_ledger_sequence``, otherwise earlier signatures are
-    invalidated.
+    ``valid_until_ledger_sequence``. Passing a different one once another node
+    of the entry carries a signature raises :exc:`ValueError` rather than
+    returning an entry whose earlier signatures may no longer verify. Every
+    signature value other than ``scvVoid`` counts, ``scvVoid`` being the marker
+    for a node still awaiting one — so a custom account contract that accepts
+    ``scvVoid`` itself as a valid signature falls outside that check; fill such
+    a node by signing the payload from :func:`build_authorization_preimage` and
+    assigning it yourself.
 
     Default account example::
 
@@ -292,8 +327,11 @@ def bls_signer(preimage: xdr.HashIDPreimage) -> xdr.SCVal:
     :return: A signed Soroban authorization entry.
     :raises:
         :exc:`ValueError`: if the entry's credential address is not a classic
-        account (``G...``) or contract (``C...``) address, or if ``for_address``
-        matches no credential node in the entry.
+        account (``G...``) or contract (``C...``) address, if ``for_address``
+        matches no credential node in the entry, or if
+        ``valid_until_ledger_sequence`` differs from the expiration ledger
+        already stored on an entry whose other nodes carry a signature other
+        than ``scvVoid``.
     """
     if isinstance(entry, str):
         entry = stellar_xdr.SorobanAuthorizationEntry.from_xdr(entry)
@@ -312,20 +350,10 @@ def bls_signer(preimage: xdr.HashIDPreimage) -> xdr.SCVal:
             f"Unsupported SorobanCredentialsType: {entry.credentials.type}."
         )
 
-    # Set the expiration before building the preimage, so the signed payload
-    # commits to the same expiration ledger stored in the credentials.
-    addr_auth.signature_expiration_ledger = stellar_xdr.Uint32(
-        valid_until_ledger_sequence
-    )
-
-    preimage = build_authorization_preimage(
-        entry, valid_until_ledger_sequence, network_passphrase
-    )
-    signature = _sign_authorization(signer, preimage)
-
     # CAP-71-01: the payload is shared across the top-level address and every
     # (possibly nested) delegate, so the signature can be written to whichever
-    # credential node(s) carry `for_address`.
+    # credential node(s) carry `for_address`. Resolve them before touching the
+    # entry, so the guard below knows which signatures are about to be replaced.
     if for_address is None:
         targets: list[
             stellar_xdr.SorobanAddressCredentials | stellar_xdr.SorobanDelegateSignature
@@ -342,6 +370,32 @@ def bls_signer(preimage: xdr.HashIDPreimage) -> xdr.SCVal:
                 "The authorization entry has no credential node for address "
                 f"{resolved.address}."
             )
+
+    # The whole entry shares one expiration ledger, so re-stamping it can
+    # silently invalidate a signature already collected from another node
+    # (CAP-71-01). Signature values are opaque, so err on the side of refusing.
+    stored_expiration = addr_auth.signature_expiration_ledger.uint32
+    if stored_expiration != valid_until_ledger_sequence and _has_signed_node_outside(
+        entry.credentials, targets
+    ):
+        raise ValueError(
+            "This authorization entry already carries a signature committed to "
+            f"signature_expiration_ledger={stored_expiration}; pass that same "
+            f"`valid_until_ledger_sequence` to add another signature (got "
+            f"{valid_until_ledger_sequence}), or start from an entry whose "
+            "other nodes are unsigned."
+        )
+
+    # Set the expiration before building the preimage, so the signed payload
+    # commits to the same expiration ledger stored in the credentials.
+    addr_auth.signature_expiration_ledger = stellar_xdr.Uint32(
+        valid_until_ledger_sequence
+    )
+
+    preimage = build_authorization_preimage(
+        entry, valid_until_ledger_sequence, network_passphrase
+    )
+    signature = _sign_authorization(signer, preimage)
     for node in targets:
         node.signature = signature
     return entry
@@ -525,7 +579,9 @@ def build_with_delegates_entry(
     :param delegates: The delegate signers to attach.
     :param signature: The top-level account's signature. Defaults to
         ``scvVoid``, which is valid for accounts that authorize purely via
-        delegated signers.
+        delegated signers. A signature already present on ``entry`` is not
+        carried over; sign the returned entry with :func:`authorize_entry`, or
+        pass the signature here.
     :return: A new ``SOROBAN_CREDENTIALS_ADDRESS_WITH_DELEGATES`` authorization
         entry; the input entry is not modified.
     :raises:

tests/contract/test_assembled_transaction.py

@@ -13,7 +13,11 @@
     scval,
 )
 from stellar_sdk import xdr as stellar_xdr
-from stellar_sdk.auth import DelegateSignature, build_with_delegates_entry
+from stellar_sdk.auth import (
+    DelegateSignature,
+    authorize_entry,
+    build_with_delegates_entry,
+)
 from stellar_sdk.contract import (
     AssembledTransaction,
     AssembledTransactionAsync,
@@ -665,3 +669,71 @@ async def test_async_needs_non_invoker_signing_by_counts_all_address_credential_
         legacy_signer.public_key,
         delegating_signer.public_key,
     }
+
+
+def _pre_signed_delegates_entry(top: Keypair, delegate: Keypair, valid_until: int):
+    """A delegates entry whose delegate has already signed at ``valid_until``."""
+    entry = build_with_delegates_entry(
+        _sample_auth_entry(
+            top.public_key,
+            stellar_xdr.SorobanCredentialsType.SOROBAN_CREDENTIALS_ADDRESS_V2,
+        ),
+        0,
+        [DelegateSignature(delegate.public_key)],
+    )
+    return authorize_entry(
+        entry,
+        delegate,
+        valid_until,
+        Network.TESTNET_NETWORK_PASSPHRASE,
+        for_address=delegate.public_key,
+    )
+
+
+def test_authorize_rejects_expiration_change_on_pre_signed_delegates_entry():
+    # authorize() can only sign the top-level node of a delegates entry, but the
+    # expiration ledger it stamps is shared with the delegates. Re-stamping it
+    # with the library default used to silently invalidate their signatures.
+    top = Keypair.random()
+    delegate = Keypair.random()
+    entry = _pre_signed_delegates_entry(top, delegate, 1000)
+    assembled, _, _ = _assembled_with_auth(top.public_key, entries=[entry])
+
+    with pytest.raises(ValueError, match=r"signature_expiration_ledger=1000"):
+        assembled.authorize(top)
+
+    # passing the delegate's expiration through signs the top level for real
+    assembled.authorize(top, valid_until_ledger_sequence=1000)
+    assert assembled.built_transaction is not None
+    op = assembled.built_transaction.transaction.operations[0]
+    assert isinstance(op, InvokeHostFunction)
+    with_delegates = op.auth[0].credentials.address_with_delegates
+    assert with_delegates is not None
+    assert (
+        with_delegates.address_credentials.signature.type
+        == stellar_xdr.SCValType.SCV_VEC
+    )
+    assert with_delegates.address_credentials.signature_expiration_ledger == (
+        stellar_xdr.Uint32(1000)
+    )
+
+
+async def test_async_authorize_rejects_expiration_change_on_pre_signed_delegates_entry():
+    top = Keypair.random()
+    delegate = Keypair.random()
+    entry = _pre_signed_delegates_entry(top, delegate, 1000)
+    assembled, _, _ = _assembled_async_with_auth(top.public_key, entries=[entry])
+
+    with pytest.raises(ValueError, match=r"signature_expiration_ledger=1000"):
+        await assembled.authorize(top)
+
+    await assembled.authorize(top, valid_until_ledger_sequence=1000)
+    assert assembled.built_transaction is not None
+    op = assembled.built_transaction.transaction.operations[0]
+    assert isinstance(op, InvokeHostFunction)
+    with_delegates = op.auth[0].credentials.address_with_delegates
+    assert with_delegates is not None
+    assert (
+        with_delegates.address_credentials.signature.type
+        == stellar_xdr.SCValType.SCV_VEC
+    )