capauth 0.3.3__tar.gz → 0.3.4__tar.gz

{capauth-0.3.3 → 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.3 → capauth-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: capauth
-Version: 0.3.3
+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.3 → 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.3 → 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.3 → 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.3 → capauth-0.3.4}/src/capauth.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: capauth
-Version: 0.3.3
+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.3 → 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