capauth 0.3.2__tar.gz → 0.3.4__tar.gz

{capauth-0.3.2 → capauth-0.3.4}/CHANGELOG.md

@@ -6,6 +6,23 @@ All notable changes to `capauth` are documented here. The format is based on
 
 ## [Unreleased]
 
+### Documentation
+
+- Added the SK-standards-aligned human identity setup and rotation runbook,
+  covering human-only key handling, revocation certificates, protected backup
+  transfer, additive trust migration, signed CAB approval, verification,
+  rollback, evidence, and recurring custody management.
+
+### Fixed
+
+- **Identity docstrings taught the wrong fqid shape.** `agent_identity.py`
+  showed `lumina@chef.skworld` in its prose, its worked example and its
+  doctest: the missing-TLD form that the N5 store migration exists to correct.
+  Verified against the live resolver, which returns `lumina@chef.skworld.io`.
+  A wrong example in the module that defines identity is what the next reader
+  or agent copies. `subject.py` deliberately keeps its legacy examples, since
+  they document the shapes the alias table normalizes.
+
 ### Added
 
 - **`capauth.pairing.proof`: a supported way to BUILD the enrollment proof card

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: capauth
-Version: 0.3.2
+Version: 0.3.4
 Summary: Capability-based Authentication — decentralized, PGP-based identity and authorization
 Author-email: smilinTux <admin@smilintux.org>
 License: GPL-3.0-or-later
@@ -317,6 +317,8 @@ capauth is the identity root of SKWorld — most of the stack links back here.
   — produces the runtime crypto self-report that makes capauth's claims evidence-backed.
 - 📐 **Standards:** [sk-standards](https://github.com/smilinTux/sk-standards) — the
   crypto, data-flow, version, and doc/SOP standards (incl. `CRYPTOGRAPHY_STANDARD`).
+- 🔐 **Human key operations:**
+  [setup, recovery, rotation, approval, and rollback](docs/HUMAN_IDENTITY_SETUP_AND_ROTATION.md).
 
 ## License
 

{capauth-0.3.2 → capauth-0.3.4}/README.md

@@ -255,6 +255,8 @@ capauth is the identity root of SKWorld — most of the stack links back here.
   — produces the runtime crypto self-report that makes capauth's claims evidence-backed.
 - 📐 **Standards:** [sk-standards](https://github.com/smilinTux/sk-standards) — the
   crypto, data-flow, version, and doc/SOP standards (incl. `CRYPTOGRAPHY_STANDARD`).
+- 🔐 **Human key operations:**
+  [setup, recovery, rotation, approval, and rollback](docs/HUMAN_IDENTITY_SETUP_AND_ROTATION.md).
 
 ## License
 

{capauth-0.3.2 → capauth-0.3.4}/SOP.md

@@ -346,6 +346,25 @@ capauth manifest sign | verify | list        # signed module manifests
 capauth token mint-audience ...              # mint an audience-scoped token
 ```
 
+### Authorization token incident check
+
+`capauth.authz.decide()` is fail-closed on token authenticity: a granting token
+must have a non-empty signature, `signature_verifies()` must succeed, it must be
+active, and its token ID must not appear in
+`$SKCAPSTONE_HOME/security/revoked-tokens.json`. Never infer trust from the
+persisted `verified` field alone. `issue_token()` must also abort before storage
+when signing fails; an unsigned compatibility token may only pass through the
+explicit, bounded legacy-grace configuration documented in `authz.py`.
+
+For an incident sweep, inventory the token payloads in
+`$SKCAPSTONE_HOME/security/tokens/`, confirm every live grant has a detached
+signature, search the revocation list for the reported token ID, and exercise
+both controls: an unsigned/tampered token is denied while a valid signed token
+is allowed. Revoke a discovered token through `capauth.tokens.revoke_token()`;
+do not delete the evidence file by hand. Preserve the test evidence from
+`tests/test_authz_signature_gate.py` and `tests/test_authz_legacy_grace.py` on
+the coordination card.
+
 > **There is NO `capauth did` command group.** Earlier revisions of this SOP and of
 > the README documented `capauth did generate` and `capauth did identity-card`; both
 > are fabrications, and running them exits non-zero with "No such command". The DID
@@ -402,6 +421,12 @@ Full protocol + claim/token format: [docs/PROTOCOL.md](docs/PROTOCOL.md),
 
 ## 8. Troubleshooting
 
+Human identity setup, custody recovery, rotation, signed approval, and rollback
+are governed by
+[docs/HUMAN_IDENTITY_SETUP_AND_ROTATION.md](docs/HUMAN_IDENTITY_SETUP_AND_ROTATION.md).
+The human performs all passphrase/private-key operations; automation may only
+prepare paths and verify public evidence.
+
 | Symptom | Likely cause | Fix |
 |---|---|---|
 | `capauth verify` fails on a valid peer | wrong public key / stale profile | re-`export-pubkey`; confirm fingerprint matches the DID/identity card |
@@ -486,4 +511,3 @@ checks:
   - name: ci.yml lint gate is ruff (section 4 says black is NOT a gate)
     run: grep -qF 'ruff format --check src/ tests/' .github/workflows/ci.yml
 -->
-

capauth-0.3.4/docs/HUMAN_IDENTITY_SETUP_AND_ROTATION.md

@@ -0,0 +1,149 @@
+# Human identity setup, recovery, and key rotation
+
+Status: operational runbook. Owner: the human identity holder. Applies to
+classical CapAuth human identities used for signed approvals and operator
+governance. This runbook follows the SK standards for provenance, reversible
+mutation, backup/retention, testing evidence, and ITIL change control.
+
+## 1. Purpose and invariants
+
+- A human private key is generated and unlocked only by that human.
+- Agents may prepare paths and verify public evidence, but never type, copy,
+  print, or forge the human passphrase or private key.
+- Rotation is additive first: retain the old public key and profile as audit
+  history, enroll the new fingerprint, verify it, then retire old trust.
+- Private keys and revocation certificates are `0600`; containing directories
+  are `0700`. Public keys may be `0644`.
+- Never paste key material or passphrases into chat, tickets, shell history,
+  source control, logs, or command output.
+- A backup is not accepted until its fingerprint and restore path are tested.
+
+## 2. State and ownership
+
+```mermaid
+flowchart LR
+    H[Human at terminal] -->|generates and unlocks| S[staging identity]
+    S -->|public fingerprint verification| V[verification gate]
+    S -->|0600 copy by human| B[two offline custody copies]
+    V -->|approved change| L[live CapAuth identity]
+    L --> R[registries and trust consumers]
+    L --> A[signed authorization envelope]
+    O[old public identity] --> X[retired audit history]
+```
+
+Canonical live home on the operator workstation is
+`~/.skcapstone/capauth`. Temporary ceremony homes and home-directory backups
+are transitional custody only and must be moved to two independent offline
+media after acceptance.
+
+## 3. Initial setup
+
+The human runs key generation personally:
+
+```bash
+install -d -m 700 "$HOME/.chef-cauth-setup"
+capauth --home "$HOME/.chef-cauth-setup" init \
+  --name Chef --email chef@skworld.io --type human \
+  --algorithm ed25519 --no-sync
+```
+
+Use a unique passphrase and retain it outside the workstation. Verify without
+printing key contents:
+
+```bash
+capauth --home "$HOME/.chef-cauth-setup" profile verify
+capauth --home "$HOME/.chef-cauth-setup" doctor custody --json
+```
+
+`doctor` will remain red until a matching revocation certificate and backup
+exist. A red custody gate is not waived.
+
+## 4. Revocation certificate and custody copies
+
+The human imports the staged key into an isolated temporary GnuPG home and
+runs `gpg --gen-revoke <fingerprint>`. Creating the certificate does not revoke
+the key. Store the resulting `root-revocation.asc` beside each protected
+private-key custody copy. Confirm:
+
+```bash
+stat -c '%a %U %G %n' \
+  "$HOME/.chef-cauth-setup/identity/private.asc" \
+  "$HOME/.chef-cauth-setup/identity/root-revocation.asc"
+```
+
+Expected mode is `600`. Maintain two independent offline copies. An on-host
+backup is only a transfer/staging copy, not the required 3-2-1 end state.
+
+## 5. Rotation workflow
+
+1. Open an ITIL change with old fingerprint, reason, affected trust surfaces,
+   maintenance window, verification plan, and rollback target.
+2. Snapshot the old public key, signed profile, custody declaration, and
+   revocation certificate into an owner-only `retired-keys/` directory.
+3. Generate the replacement in an isolated `0700` ceremony home.
+4. Verify public/private/backup fingerprints are identical and the profile
+   signature is valid.
+5. Generate and duplicate the replacement revocation certificate.
+6. Install the replacement keypair and profile with the modes in section 1.
+7. Update explicit fingerprint bindings in registries. Do not use global text
+   replacement; validate every target record before mutation.
+8. Run a fresh public-state backup and its restore verification.
+9. Run `capauth doctor custody`; all mandatory checks must be `OK`.
+10. Produce a signed, short-lived authorization and verify it through the real
+    consuming workflow.
+11. Keep both public fingerprints during the declared grace period. Revoke the
+    old key only for compromise; an unavailable secret is retired, not falsely
+    claimed revoked.
+
+## 6. Signed approval ceremony
+
+For an ATLAS/CMDB change, the authorization binds decision, target, change,
+scope, expiry, nonce, signer fingerprint, and role:
+
+```bash
+skcapstone itil cab authorize CHANGE_ID \
+  --decision approved --target TARGET --scope SCOPE \
+  --output "$HOME/.skcapstone/authorizations/CHANGE_ID.json"
+skcapstone itil cab vote CHANGE_ID \
+  --decision approved \
+  --authorization "$HOME/.skcapstone/authorizations/CHANGE_ID.json" \
+  --target TARGET --scope SCOPE
+```
+
+Read the folded change back. The named human, authenticated role,
+fingerprint, authorization ID, target, and scope must all match. Authorization
+does not bypass freeze, maintenance-window, evidence, or rollback gates.
+
+## 7. Verification and rollback
+
+Acceptance evidence:
+
+```bash
+capauth --home "$HOME/.skcapstone/capauth" profile verify
+capauth --home "$HOME/.skcapstone/capauth" doctor custody --json
+capauth manifest verify-all
+```
+
+If any check fails, stop consumers, restore the prior public/profile state from
+the named rollback directory, restore the previous registry fingerprint, and
+rerun the same checks. Never delete the failed replacement; quarantine it with
+its evidence and record the reversing event on the ITIL change.
+
+## 8. Ongoing management
+
+- Daily: custody doctor and backup freshness through the wrapped scheduler.
+- Monthly: verify permissions, registry fingerprint parity, and restore the
+  newest public-state backup into a temporary directory.
+- Quarterly: verify both offline custody media and revocation-certificate
+  readability; do not import the private key during routine inspection.
+- Before each approval: verify profile signature and exact action/change/scope.
+- On suspected compromise: freeze ATLAS, publish the held revocation
+  certificate, invalidate affected grants, rotate, and open an incident/problem.
+
+## 9. Evidence, records, and prohibited shortcuts
+
+Record fingerprints, timestamps, modes, doctor results, backup artifact ID,
+change ID, and verification outcome. Never record passphrases or private-key
+content. Prohibited shortcuts include agent-generated human keys, reusing an
+agent key as a person, unsigned votes, copying secrets through chat, accepting
+a mismatched backup, or deleting old identity history to make checks green.

{capauth-0.3.2 → capauth-0.3.4}/src/capauth/agent_identity.py

@@ -19,7 +19,7 @@ A resolved identity carries **two complementary URIs**:
 
 ``fqid``
     ``<agent>@<operator>.<realm>`` — the skcomms three-tier FQID
-    (agent @ operator . realm, e.g. ``lumina@chef.skworld``).  Derived from
+    (agent @ operator . realm, e.g. ``lumina@chef.skworld.io``).  Derived from
     ``~/.skcapstone/cluster.json`` for operator/realm; ``None`` when
     cluster.json is absent or malformed.
 
@@ -38,7 +38,7 @@ Public API
     # AgentIdentity(
     #   agent       = "lumina",
     #   capauth_uri = "capauth:lumina@skworld.io",
-    #   fqid        = "lumina@chef.skworld",
+    #   fqid        = "lumina@chef.skworld.io",
     #   fingerprint = "02BC0EB3CAD31DB691A753C70C5629AB893F9746",
     # )
 
@@ -84,7 +84,7 @@ class AgentIdentity:
         agent:        Short agent name (e.g. ``"lumina"``).
         capauth_uri:  Wire identity — ``capauth:<agent>@skworld.io``.
         fqid:         Three-tier label — ``<agent>@<operator>.<realm>``
-                      (e.g. ``"lumina@chef.skworld"``).  ``None`` when
+                      (e.g. ``"lumina@chef.skworld.io"``).  ``None`` when
                       cluster.json is not available.
         fingerprint:  40 (v4) or 64 (v6) hex PGP fingerprint from the agent's
                       CapAuth profile.  ``None`` when no real profile exists.
@@ -274,7 +274,7 @@ def resolve_agent_identity(
         >>> ident.capauth_uri
         'capauth:lumina@skworld.io'
         >>> ident.fqid   # only if cluster.json present
-        'lumina@chef.skworld'
+        'lumina@chef.skworld.io'
     """
     if agent is None:
         agent = _resolve_active_agent_name()

{capauth-0.3.2 → capauth-0.3.4}/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.4}/src/capauth.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: capauth
-Version: 0.3.2
+Version: 0.3.4
 Summary: Capability-based Authentication — decentralized, PGP-based identity and authorization
 Author-email: smilinTux <admin@smilintux.org>
 License: GPL-3.0-or-later
@@ -317,6 +317,8 @@ capauth is the identity root of SKWorld — most of the stack links back here.
   — produces the runtime crypto self-report that makes capauth's claims evidence-backed.
 - 📐 **Standards:** [sk-standards](https://github.com/smilinTux/sk-standards) — the
   crypto, data-flow, version, and doc/SOP standards (incl. `CRYPTOGRAPHY_STANDARD`).
+- 🔐 **Human key operations:**
+  [setup, recovery, rotation, approval, and rollback](docs/HUMAN_IDENTITY_SETUP_AND_ROTATION.md).
 
 ## License
 

{capauth-0.3.2 → capauth-0.3.4}/src/capauth.egg-info/SOURCES.txt

@@ -107,6 +107,7 @@ docs/CLAIMS.md
 docs/COLD_MACHINE_BOOTSTRAP_AND_DR.md
 docs/CRYPTO_SPEC.md
 docs/ENTERPRISE_MANAGED_KEYS.md
+docs/HUMAN_IDENTITY_SETUP_AND_ROTATION.md
 docs/INTEGRATION_BLUEPRINT.md
 docs/M0-capauth-api-v1.md
 docs/M0-capauth-importer-inventory.md

{capauth-0.3.2 → capauth-0.3.4}/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"