capauth 0.3.2__tar.gz → 0.3.3__tar.gz

{capauth-0.3.2 → capauth-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: capauth
-Version: 0.3.2
+Version: 0.3.3
 Summary: Capability-based Authentication — decentralized, PGP-based identity and authorization
 Author-email: smilinTux <admin@smilintux.org>
 License: GPL-3.0-or-later

{capauth-0.3.2 → capauth-0.3.3}/src/capauth/pairing/proof.py

@@ -173,6 +173,36 @@ def _is_pgp(key: Optional[str]) -> bool:
     return "BEGIN PGP" in (key or "")
 
 
+def _require_subject(subject: Optional[str]) -> str:
+    """Reject an absent or blank subject, loudly, at the call.
+
+    ``subject`` is a REQUIRED keyword on every public builder here, but a caller
+    can still hand us ``None`` at runtime (an Optional threaded down from its own
+    config, a dict lookup that missed). Falling back to a derived default there
+    is the one thing this module must never do.
+
+    Why: the challenge binds the subject, so a proof built for subject A does not
+    verify for subject B. If the builder quietly substituted its own default
+    while ``enroll_device`` was called with the caller's real subject, the device
+    would sign honestly, capauth would reject the proof, and the enrollment would
+    land on the TOFU floor behind a success response with nothing raised. That is
+    exactly the silent downgrade card N10 exists to remove.
+
+    This bit for real: capauth's derived default is the full 40-char
+    ``fingerprint_for`` value, while skchat's own derivation is a 16-char device
+    id. Two individually reasonable defaults, different signed bytes, and the
+    mismatch is invisible until the security boundary rejects it. Caught in
+    review by clawd-43 on 2026-08-17 before it shipped to a caller.
+    """
+    if subject is None or not str(subject).strip():
+        raise ProofSigningError(
+            "subject is required: the enrollment challenge binds it, so it must be "
+            "the SAME subject you pass to enroll_device(). Deriving one here would "
+            "silently change the signed bytes and downgrade the enrollment to tofu."
+        )
+    return str(subject)
+
+
 def _resolve_subject(pubkey: str, subject: Optional[str]) -> tuple[str, str]:
     """Derive ``(fingerprint, canonical_subject)`` exactly as ``enroll_device`` will.
 
@@ -208,7 +238,7 @@ def _coerce_mode(mode: EnrollmentMode | str) -> EnrollmentMode:
 def enrollment_challenge(
     pubkey: str,
     *,
-    subject: Optional[str] = None,
+    subject: str,
     mode: EnrollmentMode | str = EnrollmentMode.VERIFIED,
 ) -> bytes:
     """The exact bytes an enrollment's proof must sign, from the PUBLIC key alone.
@@ -245,7 +275,7 @@ def enrollment_challenge(
         PairingError: If ``mode`` is not a known enrollment mode.
     """
     resolved = _coerce_mode(mode)
-    fingerprint, canonical = _resolve_subject(pubkey, subject)
+    fingerprint, canonical = _resolve_subject(pubkey, _require_subject(subject))
     if resolved is EnrollmentMode.ATTESTED:
         return attested_challenge(fingerprint, canonical)
     if resolved is EnrollmentMode.VERIFIED:
@@ -340,8 +370,8 @@ def build_verified_proof(
     pubkey: str,
     *,
     private_key: Any,
+    subject: str,
     passphrase: str = "",
-    subject: Optional[str] = None,
 ) -> EnrollmentProof:
     """Sign the ``verified`` enrollment challenge with the device's OWN key.
 
@@ -379,7 +409,7 @@ def build_verified_proof(
         capauth.exceptions.SubjectNamingError: If ``subject`` does not conform
             to the canonical fqid grammar even after alias translation.
     """
-    fingerprint, canonical = _resolve_subject(pubkey, subject)
+    fingerprint, canonical = _resolve_subject(pubkey, _require_subject(subject))
     challenge = verified_challenge(fingerprint, canonical)
     signature = _sign(challenge, private_key, passphrase, pgp=_is_pgp(pubkey))
     _self_check(pubkey, signature, challenge, what="verified proof")
@@ -398,8 +428,8 @@ def build_attested_proof(
     *,
     operator_pubkey: str,
     operator_private_key: Any,
+    subject: str,
     passphrase: str = "",
-    subject: Optional[str] = None,
 ) -> EnrollmentProof:
     """Sign the ``attested`` challenge with a VOUCHING OPERATOR's key.
 
@@ -440,7 +470,7 @@ def build_attested_proof(
         capauth.exceptions.SubjectNamingError: If ``subject`` does not conform
             to the canonical fqid grammar even after alias translation.
     """
-    fingerprint, canonical = _resolve_subject(pubkey, subject)
+    fingerprint, canonical = _resolve_subject(pubkey, _require_subject(subject))
     challenge = attested_challenge(fingerprint, canonical)
     signature = _sign(challenge, operator_private_key, passphrase, pgp=_is_pgp(operator_pubkey))
     _self_check(operator_pubkey, signature, challenge, what="attestation")

{capauth-0.3.2 → capauth-0.3.3}/src/capauth.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: capauth
-Version: 0.3.2
+Version: 0.3.3
 Summary: Capability-based Authentication — decentralized, PGP-based identity and authorization
 Author-email: smilinTux <admin@smilintux.org>
 License: GPL-3.0-or-later

{capauth-0.3.2 → capauth-0.3.3}/tests/test_enrollment_proof_helper.py

@@ -155,10 +155,22 @@ def test_attested_proof_round_trips_through_enroll_device(tmp_path):
 
 
 def test_helper_defaults_subject_to_the_device_fingerprint_like_enroll_device(tmp_path):
-    """Omitting ``subject`` on both sides still agrees: both derive device:<fp>."""
+    """An EXPLICIT subject on both sides agrees end to end.
+
+    This test used to omit ``subject`` and rely on the builder and
+    ``enroll_device`` deriving the same default. That default was removed: two
+    individually reasonable defaults (capauth's 40-char fingerprint, skchat's
+    16-char device id) produce different signed bytes, and the mismatch is
+    invisible until the security boundary rejects it. The subject is now
+    required, so the agreement is asserted rather than assumed.
+    """
     bundle = _pgp_keypair()
+    subject = fingerprint_for(bundle.public_armor)
     proof = build_verified_proof(
-        bundle.public_armor, private_key=bundle.private_armor, passphrase=TEST_PASSPHRASE
+        bundle.public_armor,
+        private_key=bundle.private_armor,
+        subject=subject,
+        passphrase=TEST_PASSPHRASE,
     )
 
     enrollment = enroll_device(
@@ -412,11 +424,19 @@ def test_building_with_a_WRONG_PASSPHRASE_raises():
 def test_building_with_a_NON_KEY_raises_rather_than_returning_an_empty_proof():
     bundle = _pgp_keypair()
     with pytest.raises(ProofSigningError):
-        build_verified_proof(bundle.public_armor, private_key="not a key at all")
+        build_verified_proof(
+            bundle.public_armor,
+            private_key="not a key at all",
+            subject=fingerprint_for(bundle.public_armor),
+        )
 
     pubkey_b64, _ = _device_keypair()
     with pytest.raises(ProofSigningError):
-        build_verified_proof(pubkey_b64, private_key=b"-----BEGIN PRIVATE KEY-----\nnope\n")
+        build_verified_proof(
+            pubkey_b64,
+            private_key=b"-----BEGIN PRIVATE KEY-----\nnope\n",
+            subject=fingerprint_for(pubkey_b64),
+        )
 
 
 def test_a_built_proof_is_never_empty():
@@ -430,3 +450,65 @@ def test_a_built_proof_is_never_empty():
     assert proof.proof
     assert dict(proof) == {"proof": proof.proof}
     assert "operator_pubkey" not in dict(proof)
+
+
+# --- subject is REQUIRED (regression: two reasonable defaults, different bytes) ---
+
+
+def test_subject_is_required_on_every_public_builder():
+    """A derived default here silently changes the SIGNED BYTES.
+
+    capauth's own default was the full 40-char `fingerprint_for` value. skchat,
+    the helper's first caller, derives a 16-char device id. Both defensible in
+    isolation. But a proof built with capauth's default, then handed to
+    `enroll_device` with skchat's real subject, does not verify: the device signs
+    honestly, capauth rejects, and the enrollment lands on the TOFU floor behind
+    a success response with nothing raised. That is the exact silent downgrade
+    card N10 exists to remove, reintroduced by the convenience meant to close it.
+
+    Caught in review by clawd-43 on 2026-08-17, before any caller shipped it.
+    """
+    bundle = _pgp_keypair()
+
+    for call in (
+        lambda: enrollment_challenge(bundle.public_armor),
+        lambda: build_verified_proof(
+            bundle.public_armor,
+            private_key=bundle.private_armor,
+            passphrase=TEST_PASSPHRASE,
+        ),
+    ):
+        with pytest.raises(TypeError, match="subject"):
+            call()
+
+
+@pytest.mark.parametrize("blank", [None, "", "   "])
+def test_an_explicitly_blank_subject_raises_rather_than_deriving_one(blank):
+    """The signature makes it required; this makes a runtime None fail too.
+
+    A caller can still thread an Optional down from its own config and hand us
+    None. Falling back to a derived default there is the failure this module
+    must never have.
+    """
+    bundle = _pgp_keypair()
+
+    with pytest.raises(ProofSigningError, match="subject is required"):
+        enrollment_challenge(bundle.public_armor, subject=blank)
+
+    with pytest.raises(ProofSigningError, match="subject is required"):
+        build_verified_proof(
+            bundle.public_armor,
+            private_key=bundle.private_armor,
+            subject=blank,
+            passphrase=TEST_PASSPHRASE,
+        )
+
+
+def test_two_different_subjects_produce_different_challenges():
+    """The property the whole guard exists to protect, asserted directly."""
+    bundle = _pgp_keypair()
+    full = fingerprint_for(bundle.public_armor)
+
+    assert enrollment_challenge(bundle.public_armor, subject=full) != enrollment_challenge(
+        bundle.public_armor, subject=full[:16]
+    ), "challenge must bind the subject, or a subject mismatch would go unnoticed"