capauth 0.3.4__tar.gz → 0.3.6__tar.gz

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

@@ -6,6 +6,11 @@ All notable changes to `capauth` are documented here. The format is based on
 
 ## [Unreleased]
 
+- Recorded the verified 2026-08-20 Chef custody/signing ceremony and the
+  deferred passphrase-disclosure response (`da8a6401`) in the human identity
+  runbook, including the safe hidden-input pattern and honest residual-risk
+  language.
+
 ### Documentation
 
 - Added the SK-standards-aligned human identity setup and rotation runbook,
@@ -15,6 +20,11 @@ All notable changes to `capauth` are documented here. The format is based on
 
 ### Fixed
 
+- Restored the declared Python 3.10 support for delegated capabilities by using
+  compatible UTC, string-enum, `Never`, and `Self` definitions. Downstream
+  SKVault installs can again complete their full 3.10 test gate.
+- Restored Ruff formatting for the delegated-capability and CLI modules so the
+  enforced lint gate agrees with the released source.
 - **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.
@@ -25,6 +35,22 @@ All notable changes to `capauth` are documented here. The format is based on
 
 ### Added
 
+- **A strict reusable delegated capability-chain contract.**
+  `capauth.delegated` adds a versioned request-local transport, complete-chain
+  verification, bounded monotonic attenuation, current issuer and principal
+  policy checks for every chain member, ancestor and leaf revocation, atomic
+  one-use replay reservation, and exact-scope sanitized decisions. Recursive
+  duplicate JSON members, unknown fields, ambiguous envelopes, missing or
+  reordered ancestors, over-depth chains, broadened children, stale principals,
+  untrusted issuers, revoked credentials, expired credentials, and replay all
+  fail closed. Expiry and current-state snapshots are refreshed after signature,
+  replay, and durable audit work before allow. Any policy revision change during
+  audit denies and requires a fresh invocation. Production storage remains application supplied;
+  included in-memory backends are explicitly limited to tests and isolated local
+  development. Raw credentials and signature bytes are redacted from values,
+  decisions, audit records, and chained exceptions. See
+  `docs/DELEGATED_CAPABILITIES.md`.
+
 - **`capauth.pairing.proof`: a supported way to BUILD the enrollment proof card
   N10 made mandatory.** `83c1fa2` made `proof` required for `verified` and
   `operator_pubkey` + `attestation` required for `attested`, but shipped the

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: capauth
-Version: 0.3.4
+Version: 0.3.6
 Summary: Capability-based Authentication — decentralized, PGP-based identity and authorization
 Author-email: smilinTux <admin@smilintux.org>
 License: GPL-3.0-or-later
@@ -29,6 +29,7 @@ Requires-Dist: PGPy>=0.6
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: rich>=13.0
 Requires-Dist: httpx>=0.25
+Requires-Dist: typing-extensions>=4.8
 Provides-Extra: skcapstone
 Requires-Dist: skcapstone>=0.6.8; extra == "skcapstone"
 Provides-Extra: gnupg
@@ -182,8 +183,11 @@ capauth login https://forgejo.local           # passwordless PGP login to a serv
 ```
 
 Your keypair and profile live at `~/.capauth/` — on your machine, under your
-keys. Use `--sync` on `init` (or `capauth sync`) to replicate the identity across
-all Syncthing mesh nodes so every host shares one keypair.
+keys. Use `--sync` on `init` (or `capauth sync`) to distribute the public
+identity across Syncthing mesh nodes. CapAuth writes folder-root exclusions
+before enabling sync so private keys, root revocation certificates, keystores,
+backups, passphrases, and environment files remain local. Provision scoped
+service/node signers separately; do not use public sync as private-key recovery.
 
 ## What capauth provides
 
@@ -197,6 +201,7 @@ all Syncthing mesh nodes so every host shares one keypair.
 | **Verification service** | A FastAPI service that turns a signed challenge into OIDC claims — passwordless PGP login for any OIDC app (`capauth-service`) |
 | **Peer mesh** | Discover and verify sovereign peers over mDNS, shared filesystem, and Syncthing — no servers (`capauth mesh`, `discover`, `peers`) |
 | **PMA membership** | Fiducia Communitatis — PGP-signed, steward-countersigned membership claims (`capauth pma request/approve/verify/revoke`) |
+| **Delegated capabilities** | Strict complete-chain validation with current issuer, principal, revocation, replay, attenuation, exact-scope, and sanitized-decision interfaces (`capauth.delegated`) |
 | **Org registry** | Register with a sovereign org; emits a signed registry entry + PMA request (`capauth register`) |
 | **Integration generators** | One-shot config for third-party login, e.g. Forgejo OAuth2/OIDC (`capauth setup forgejo`) |
 | **skcapstone adapter** | Default-on-by-presence: routes auth events to `sk-alert`, registers a key-rotation check with `skscheduler` |
@@ -233,7 +238,8 @@ verification service uses).
 capauth init --name "Chef" --email "..."     # create sovereign profile (PGP keypair)
 capauth profile show | verify                 # display / verify signature integrity
 capauth export-pubkey [-o file.asc]          # export ASCII-armored public key
-capauth sync                                  # replicate ~/.capauth/ across Syncthing mesh
+capauth sync                                  # distribute public identity; keep secrets local
+capauth doctor estate --manifest estate.json # find legacy/retired/conflict key copies
 
 # Verification
 capauth verify --pubkey peer.pub.asc         # challenge-response round-trip
@@ -283,6 +289,7 @@ rides in the payload `event` field so routing stays severity-based.
 | **[Crypto Spec](docs/CRYPTO_SPEC.md)** | PGP implementation, key management, challenge-response details |
 | **[Protocol](docs/PROTOCOL.md)** | the CapAuth wire protocol specification |
 | **[Claims](docs/CLAIMS.md)** | capability claims and token format |
+| **[Strict delegated capabilities](docs/DELEGATED_CAPABILITIES.md)** | versioned chain transport, verification invariants, backend contracts, and application composition |
 | **[Integration Blueprint](docs/INTEGRATION_BLUEPRINT.md)** | third-party integration guide |
 | **[Cold-Machine Bootstrap & DR](docs/COLD_MACHINE_BOOTSTRAP_AND_DR.md)** | standing capauth back up on a blank box + disaster recovery: the restore-not-regenerate rule, the ordered restore chain, and the operator checklist |
 | **[authentik-capauth](docs/authentik-capauth.md)** | the custom Authentik image with the CapAuth PGP stage baked in — build (`AK_VERSION`, version-agnostic venv install, frontend rebuild), SKStacks deploy + `lifecycle.migrate` override, and the four build/migrate gotchas |

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

@@ -120,8 +120,11 @@ capauth login https://forgejo.local           # passwordless PGP login to a serv
 ```
 
 Your keypair and profile live at `~/.capauth/` — on your machine, under your
-keys. Use `--sync` on `init` (or `capauth sync`) to replicate the identity across
-all Syncthing mesh nodes so every host shares one keypair.
+keys. Use `--sync` on `init` (or `capauth sync`) to distribute the public
+identity across Syncthing mesh nodes. CapAuth writes folder-root exclusions
+before enabling sync so private keys, root revocation certificates, keystores,
+backups, passphrases, and environment files remain local. Provision scoped
+service/node signers separately; do not use public sync as private-key recovery.
 
 ## What capauth provides
 
@@ -135,6 +138,7 @@ all Syncthing mesh nodes so every host shares one keypair.
 | **Verification service** | A FastAPI service that turns a signed challenge into OIDC claims — passwordless PGP login for any OIDC app (`capauth-service`) |
 | **Peer mesh** | Discover and verify sovereign peers over mDNS, shared filesystem, and Syncthing — no servers (`capauth mesh`, `discover`, `peers`) |
 | **PMA membership** | Fiducia Communitatis — PGP-signed, steward-countersigned membership claims (`capauth pma request/approve/verify/revoke`) |
+| **Delegated capabilities** | Strict complete-chain validation with current issuer, principal, revocation, replay, attenuation, exact-scope, and sanitized-decision interfaces (`capauth.delegated`) |
 | **Org registry** | Register with a sovereign org; emits a signed registry entry + PMA request (`capauth register`) |
 | **Integration generators** | One-shot config for third-party login, e.g. Forgejo OAuth2/OIDC (`capauth setup forgejo`) |
 | **skcapstone adapter** | Default-on-by-presence: routes auth events to `sk-alert`, registers a key-rotation check with `skscheduler` |
@@ -171,7 +175,8 @@ verification service uses).
 capauth init --name "Chef" --email "..."     # create sovereign profile (PGP keypair)
 capauth profile show | verify                 # display / verify signature integrity
 capauth export-pubkey [-o file.asc]          # export ASCII-armored public key
-capauth sync                                  # replicate ~/.capauth/ across Syncthing mesh
+capauth sync                                  # distribute public identity; keep secrets local
+capauth doctor estate --manifest estate.json # find legacy/retired/conflict key copies
 
 # Verification
 capauth verify --pubkey peer.pub.asc         # challenge-response round-trip
@@ -221,6 +226,7 @@ rides in the payload `event` field so routing stays severity-based.
 | **[Crypto Spec](docs/CRYPTO_SPEC.md)** | PGP implementation, key management, challenge-response details |
 | **[Protocol](docs/PROTOCOL.md)** | the CapAuth wire protocol specification |
 | **[Claims](docs/CLAIMS.md)** | capability claims and token format |
+| **[Strict delegated capabilities](docs/DELEGATED_CAPABILITIES.md)** | versioned chain transport, verification invariants, backend contracts, and application composition |
 | **[Integration Blueprint](docs/INTEGRATION_BLUEPRINT.md)** | third-party integration guide |
 | **[Cold-Machine Bootstrap & DR](docs/COLD_MACHINE_BOOTSTRAP_AND_DR.md)** | standing capauth back up on a blank box + disaster recovery: the restore-not-regenerate rule, the ordered restore chain, and the operator checklist |
 | **[authentik-capauth](docs/authentik-capauth.md)** | the custom Authentik image with the CapAuth PGP stage baked in — build (`AK_VERSION`, version-agnostic venv install, frontend rebuild), SKStacks deploy + `lifecycle.migrate` override, and the four build/migrate gotchas |

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

@@ -182,6 +182,11 @@ its `integration` job is `continue-on-error: true`, so that job is red-tolerant
 design. `ci.yml` is the honest gate. Add the `skcapstone doctor` identity invariants
 on top when the change touches the resolver.
 
+The Python 3.10 leg is a supported compatibility boundary, not an advisory job.
+Shared modules must use `typing_extensions` for post-3.10 typing features and
+portable UTC and string-enum definitions. A new feature is not releasable if
+importing it breaks a supported matrix interpreter.
+
 ---
 
 ## 5. Release / Deploy

{capauth-0.3.4 → capauth-0.3.6}/docs/ARCHITECTURE.md

@@ -45,7 +45,7 @@ flowchart TD
     INIT["capauth init<br/>--name --email --type --algorithm"] --> GEN["crypto backend generates keypair<br/>(pgpy default, or gnupg)"]
     GEN --> WRITE["write sovereign profile<br/>~/.capauth/identity/ (public + private armor)<br/>profile.json (signed)"]
     WRITE --> SYNC{"--sync?"}
-    SYNC -->|yes, Syncthing present| REPL["replicate ~/.capauth/<br/>across all mesh nodes"]
+    SYNC -->|yes, Syncthing present| REPL["distribute public identity<br/>secrets remain local"]
     SYNC -->|no| LOCAL["identity stays local"]
     WRITE --> USE["profile.json = source of truth"]
     USE --> SHOW["capauth profile show"]
@@ -273,7 +273,8 @@ flowchart LR
 | `discovery/` | Discovery backends — `file_discovery.py`, `mdns.py`, `syncthing.py` |
 | `pma.py` | PMA membership — request / approve / verify / revoke, `MembershipClaim` |
 | `registry.py` | `RegistryEntry`, sovereign org registry, `build_capauth_uri` |
-| `sync.py` | Syncthing identity replication helpers |
+| `sync.py` | Syncthing public-identity distribution with secret exclusions |
+| `estate.py` | Estate manifest, alternate-home/keyring discovery, retirement gate, evidence |
 | `integration.py` | skcapstone adapter — `alert()` (sk-alert), `ensure_schedule()` (skscheduler), `register_self()`; default-on-by-presence |
 | `apps.py` | App/service descriptor helpers |
 | `integrations/forgejo/` | Forgejo OIDC provider + auth flow + config generator |

{capauth-0.3.4 → capauth-0.3.6}/docs/COLD_MACHINE_BOOTSTRAP_AND_DR.md

@@ -242,10 +242,10 @@ new material to the classical root or to a per-agent key.
 
 > ### STOP - REQUIRES CHEF (private key files)
 
-Restore the operator/root identity directory from the sovereign backup. This is
-the Phase-0 tarball from the ceremony doc, or the Syncthing-replicated
-`~/.capauth/` (capauth replicates the identity across mesh nodes via `capauth
-sync` / `--sync`).
+Restore the operator/root identity directory from the encrypted sovereign
+custody backup. Syncthing public-identity distribution (`capauth sync` /
+`--sync`) deliberately excludes `private.*` and `root-revocation.asc`; it is not
+a private-key recovery source.
 
 ```sh
 # from the backup tarball (created per ROOT_ROTATION_CEREMONY.md Phase 0):
@@ -256,9 +256,10 @@ capauth profile show                          # confirm entity + fingerprint
 capauth profile verify                         # PGP self-signature must verify
 ```
 
-If you replicate via Syncthing instead, let `~/.capauth/` sync in, then run the
-same two verify commands. Do **not** run `capauth init` on this machine - that
-generates a *new* keypair and would fork the operator identity.
+After restoring the private key from encrypted custody, public Syncthing state
+may fill in non-secret profile material. Run the same two verify commands. Do
+**not** run `capauth init` on this machine - that generates a *new* keypair and
+would fork the operator identity.
 
 ### Step 5 - Restore agent profiles and identity.json (do NOT mint)
 

capauth-0.3.6/docs/DELEGATED_CAPABILITIES.md

@@ -0,0 +1,113 @@
+# Strict delegated capabilities
+
+`capauth.delegated` is a reusable verification contract for short-lived,
+one-use capability chains. It is a library boundary, not an authorization
+server. An application still owns its policy, current principal registry,
+issuer policy, revocation store, durable replay reservation, and audit sink.
+
+The contract verifies all authority presented for one protected invocation:
+
+- a versioned transport contains the leaf and the complete ordered ancestor chain;
+- every token uses the existing issuer-pinned CapAuth signed-token format;
+- every root, ancestor, leaf, and authenticated request principal must match a
+  current active principal-policy snapshot;
+- every issuer must be currently trusted for the exact capability, audience,
+  and principal kind it signed;
+- every child names the exact parent credential digest, stays within the signed
+  depth bound, keeps all exact scope fields, and can only add constraints or
+  narrow an unbound resource identifier;
+- revocation is checked for the leaf and every ancestor;
+- the leaf is atomically reserved before allow, making it one-use;
+- expiry is checked before and after signature work, after replay reservation,
+  and after durable audit immediately before returning allow;
+- issuer, principal, and revocation state is refreshed both before and after
+  audit; any otherwise-valid policy revision change during audit denies and
+  requires a fresh invocation;
+- allow and deny results contain exact scope and policy revisions, but never raw
+  credentials, signatures, token metadata, or exception causes.
+
+## Wire contract
+
+A direct root token may be presented as its exact `skcapstone_token` JSON.
+Delegated authority uses this envelope:
+
+```json
+{
+  "capauth_presented_capability": "1.0",
+  "chain": {
+    "ancestors": ["<root token>", "<optional parent token>"],
+    "leaf": "<leaf token>"
+  }
+}
+```
+
+`parse_authorization_bearer()` rejects unknown fields, wrong versions,
+over-depth or repeated credentials, oversized values, ambiguous shapes, and
+duplicate JSON object members at every parsed depth. `PresentedCapability`
+redacts `str()` and `repr()` and refuses serialization so bearer bytes remain
+request-local.
+
+An audit sink must preserve append order for a `decision_id`. Most attempts
+produce one record with `attempt_sequence=1`. If expiry, revocation, or policy
+state changes while the first allow record is being durably written, CapAuth
+appends a compensating denial with `attempt_sequence=2` and never returns the
+allow. Audit consumers treat the highest sequence as the terminal disposition.
+
+## Application composition
+
+```python
+from capauth.delegated import (
+    AuthorizationRequest,
+    CapabilityAuthorizer,
+    CapabilityScope,
+    Principal,
+    parse_authorization_bearer,
+)
+
+request = AuthorizationRequest(
+    principal=Principal(
+        principal_id="current-session-id",
+        subject="agent@example.test",
+        kind="agent",
+    ),
+    scope=CapabilityScope(
+        audience="records-api",
+        target="record.read",
+        capability="records.read",
+        operation="read",
+        resource_type="record",
+        resource_id="record-7",
+        constraints=frozenset({"tenant:blue"}),
+    ),
+    correlation_id="request-123",
+)
+
+presented = parse_authorization_bearer(bearer_value)
+decision = authorizer.authorize(presented, request)
+```
+
+Construct `CapabilityAuthorizer` with production implementations of
+`TrustedIssuerBackend`, `PrincipalPolicyBackend`, `RevocationBackend`,
+`ReplayBackend`, and `AuditSink`. The included in-memory implementations are
+only for tests and isolated local development. They do not coordinate across
+processes or hosts.
+
+By default, signature checks use the existing
+`CapAuthSignatureVerifier`, which pins the detached OpenPGP signature to the
+issuer named by the signed payload. Tests may inject a `SignatureVerifier`
+without changing any other policy boundary.
+
+## Operational requirements
+
+Production callers should:
+
+1. derive `AuthorizationRequest.principal` from authentication, never request JSON;
+2. derive the complete `CapabilityScope` from trusted route and resource data;
+3. use authoritative, fail-closed current-state backends;
+4. implement replay reservation as one atomic durable operation shared by every worker;
+5. persist only `AuthorizationDecision`, never a bearer or parsed token;
+6. discard `PresentedCapability` after the request finishes.
+
+The signer interface accepts payload bytes and returns a detached signature.
+Private key custody remains with the configured OpenPGP backend, hardware token,
+or signing sidecar. This module never accepts, serializes, or stores a private key.

capauth-0.3.6/docs/DOWNSTREAM_DURABLE_BACKENDS.md

@@ -0,0 +1,85 @@
+# Downstream durable backend integration checklist
+
+This checklist is for consumers that persist CapAuth authorization state
+(revocations, replay reservations, principal snapshots, issuer policy) in
+their own PostgreSQL database. CapAuth provides the capability token model,
+verification, and contracts. The consumer owns the schema, the roles, the
+grants, and the migrations. Every pitfall below was discovered by a red
+gate in the first reference consumer, not by documentation.
+
+## 1. Provision roles before migrations
+
+Migration runner roles are deliberately least-privilege and cannot create
+roles (`NOCREATEROLE`). Any role your migrations `GRANT` to must be created
+by an administrator provisioning step that runs before the migration runner.
+
+- Create grantee roles idempotently in a provisioning script, never inside a
+  digest-pinned migration.
+- Use the same least-privilege attribute profile as the migrator:
+  `LOGIN NOSUPERUSER NOCREATEDB NOCREATEROLE NOINHERIT NOBYPASSRLS
+  NOREPLICATION`.
+- Reject role-graph membership and object ownership for runtime roles at
+  provision time, and read the profile back after creating it. Fail closed
+  on any drift.
+- Document every role class (migrator, per-principal runtime logins, shared
+  function grantees) and how they relate. An undocumented grantee inside a
+  security migration is a finding, not a detail.
+
+## 2. Re-apply privilege hardening after any function re-creation
+
+PostgreSQL grants `EXECUTE` on new functions to `PUBLIC` by default. The
+durable CapAuth functions are `SECURITY DEFINER`, so a missed revoke is a
+real privilege leak, not hygiene.
+
+- Every `CREATE FUNCTION` for a CapAuth backend function must be followed,
+  in the same migration, by `REVOKE ALL ON FUNCTION <signature> FROM
+  PUBLIC` and the explicit `GRANT EXECUTE ... TO <role>`.
+- `DROP FUNCTION` plus `CREATE FUNCTION` discards all previous revokes and
+  grants. `CREATE OR REPLACE FUNCTION` preserves them. Prefer `CREATE OR
+  REPLACE`; if a signature change forces `DROP` plus `CREATE`, re-apply
+  every privilege statement from the original migration.
+- Down migrations that drop and restore a function must restore its
+  privilege state as well, or the restored object silently changes the
+  security posture.
+- Add a lint rule over your migration set so this class is caught by
+  tooling. The reference consumer lints that every definer function carries
+  its `REVOKE FROM PUBLIC` and that re-created functions re-apply prior
+  grants.
+
+## 3. Verify grants by readback, not by construction
+
+Do not trust that the provisioning script produced the intended privilege
+set. Read the effective privileges back and compare against an exact
+allowlist.
+
+- `has_function_privilege` and `information_schema.role_table_grants`
+  include privileges inherited through `PUBLIC`. That is the point: the
+  readback must see what a role can actually do.
+- Fail provisioning when the readback differs from the allowlist in either
+  direction (missing or extra privileges).
+- Repeat the role drift check at application startup; RLS cannot contain a
+  login once an administrator grants it `BYPASSRLS`, so role governance is a
+  standing deployment trust boundary.
+
+## 4. Test against a real database
+
+Fake executors cannot observe default `PUBLIC` grants, trigger behavior, or
+RLS interaction. The exact surface that is the production prerequisite is
+the one that must have real-database integration coverage.
+
+- Run the full migration set against a disposable PostgreSQL (for example a
+  digest-pinned container with tmpfs storage) in CI.
+- Exercise the definer functions through the same provisioning path
+  production uses, including concurrent replay-reservation attempts.
+- Verify the complete down/up cycle: after a rollback, functions, triggers,
+  and privilege state must match the pre-migration baseline.
+
+## Ownership summary
+
+| Artifact | Owner |
+|----------|-------|
+| Token model, verification, capability contracts | CapAuth library |
+| Schema, tables, definer functions, triggers | Consumer migrations |
+| Roles and their least-privilege profiles | Consumer provisioning |
+| Grants and PUBLIC revokes | Consumer migrations, verified by readback |
+| Migration lint and integration qualification | Consumer CI |

{capauth-0.3.4 → capauth-0.3.6}/docs/HUMAN_IDENTITY_SETUP_AND_ROTATION.md

@@ -147,3 +147,34 @@ 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.
+
+## 10. Verified 2026-08-20 Chef rotation and follow-up
+
+The governed recovery ceremony replaced the unavailable prior Chef signing key
+with fingerprint `ADAD14CCAC8D6D0BF5A4209DB994E78200BF6422`. The prior public
+identity was retained under the owner-only `retired-keys/` history, the live
+registry was updated additively, a fresh public-state backup was restore-tested,
+and `capauth doctor custody` passed. The authenticated authorization for change
+`chg-a543c87b` was consumed once and the canonical ITIL fold reported the change
+approved. The fleet `_freeze.json` and `_protected.json` plane files were then
+signed and verified against the new Chef key; signing did not unfreeze ATLAS.
+
+During the plane-signing ceremony, the passphrase was accidentally disclosed in
+terminal/chat history and briefly materialized as a plaintext filename. The file
+was securely removed, but deletion does not make a disclosed secret private
+again. Rotation was explicitly deferred by the owner and is tracked as high
+priority card `da8a6401`. Until that card closes:
+
+- never copy the disclosed value into tickets, documentation, commands, or new
+  configuration;
+- use hidden interactive input only when a governed signing ceremony is
+  unavoidable;
+- do not claim the passphrase is uncompromised; and
+- preserve the same fingerprint during passphrase-only re-protection unless a
+  full key rotation is independently required.
+
+The command anti-pattern was `echo SECRET > $CAPAUTH_PASSPHRASE`: shell
+redirection treats the expanded secret as a path, while the signer expects the
+environment variable itself to contain the secret. The supported pattern is a
+hidden prompt followed by a short-lived exported variable, immediate `unset`,
+and no shell tracing. No secret literal belongs in this runbook.

capauth-0.3.6/docs/IDENTITY_ESTATE.md

@@ -0,0 +1,128 @@
+# Identity estate discovery and retirement
+
+`capauth doctor custody` validates one configured identity. `capauth doctor
+estate` validates the wider machine estate: canonical and legacy CapAuth roots,
+SKCapstone agent/named-identity roots, alternate user homes, GnuPG keyrings, and
+Syncthing folders which contain those roots.
+
+The workflow is read-only. It never removes a key and never emits private key or
+passphrase bytes. An optional evidence file contains paths, primary
+fingerprints, manifest digest, classifications, and results.
+
+## Authoritative manifest
+
+Keep `estate.json` in the CapAuth home or pass it explicitly with `--manifest`.
+Version 1 distinguishes human, service, and node identities, records lifecycle
+state, constrains active private-key placement, and links retired fingerprints
+to verified encrypted quarantine:
+
+```json
+{
+  "version": 1,
+  "identities": [
+    {
+      "fingerprint": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
+      "status": "active",
+      "identity_type": "human",
+      "label": "operator",
+      "allowed_secret_roots": [
+        "/home/operator/.skcapstone/identities/operator/capauth"
+      ]
+    },
+    {
+      "fingerprint": "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
+      "status": "retired",
+      "identity_type": "service",
+      "label": "former service signer",
+      "quarantine": {
+        "archive": "/custody/capauth/retired-service.tar.gpg",
+        "sha256": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
+        "verified_at": "2026-08-21T00:00:00Z",
+        "verified_by": "operator"
+      }
+    }
+  ]
+}
+```
+
+Fingerprints must be full 40- or 64-hex OpenPGP primary fingerprints.
+`identity_type` is `human`, `service`, or `node`; `status` is `active` or
+`retired`. Paths may be absolute or relative to the manifest.
+
+For retired identities, `archive` must exist and end in `.gpg`, and its current
+SHA-256 must match the manifest. `verified_at` and `verified_by` are operator
+attestations that the encrypted archive was decrypt-tested and its expected
+members/fingerprints were checked. The hash check does not replace that
+decryptability test.
+
+## Audit
+
+Run against the current user:
+
+```bash
+capauth doctor estate \
+  --manifest ~/.skcapstone/capauth/estate.json \
+  --evidence /var/tmp/capauth-estate-evidence.json
+```
+
+Name every alternate home. This prevents a different login home from escaping
+the inventory:
+
+```bash
+capauth doctor estate \
+  --manifest /path/to/estate.json \
+  --user-home /home/operator \
+  --user-home /home/alternate
+```
+
+Use repeatable `--root` for identities outside the known layouts and
+`--syncthing-config` for nonstandard Syncthing configuration paths. GnuPG
+keyring inspection is on by default; `--no-gpg` exists for hermetic tests.
+
+The command exits nonzero for:
+
+- physical legacy and canonical trees which diverge;
+- private keys outside their declared custody roots;
+- unmanifested private keys;
+- any discovered retired key copy;
+- Syncthing conflict copies;
+- missing private-key or root-revocation ignore rules at the actual Syncthing
+  folder root;
+- absent, non-encrypted, or hash-mismatched quarantine evidence.
+
+An unmanifested public key and multiple copies of the same active secret key
+warn. Public keys classified as active and correctly placed active private keys
+pass.
+
+## Retirement gate
+
+1. Record the fingerprint as `retired`; do not delete anything.
+2. Stream the complete material into an encrypted `.gpg` quarantine archive.
+3. Decrypt-test the archive in a temporary location and verify expected
+   fingerprints/members.
+4. Record the archive SHA-256 and the operator attestation in the manifest.
+5. Run `capauth doctor estate --evidence ...`. The quarantine check must be
+   `OK`; discovered retired copies will still be `FAIL`.
+6. Under an approved change, remove only the exact reported copies and GnuPG
+   primary fingerprints.
+7. Rerun the audit. Retired-copy findings must be gone while quarantine remains
+   `OK`. Attach the evidence file and manifest digest to the change record.
+
+This two-run pattern makes removal contingent on verified, encrypted,
+recoverable custody and produces evidence without automating destructive key
+deletion.
+
+## Syncthing boundary
+
+`capauth sync` now writes required `.stignore` rules before registering a
+folder and fails closed if it cannot do so. Running it against an already
+configured identity root also repairs missing required exclusions. At minimum,
+the folder root must contain:
+
+```text
+**/private.*
+**/root-revocation.asc
+```
+
+The setup command also excludes common passphrase, environment, SQLite, and
+backup paths. Treat synced state as public distribution, never custody.

{capauth-0.3.4 → capauth-0.3.6}/pyproject.toml

@@ -32,6 +32,7 @@ dependencies = [
     "pyyaml>=6.0",
     "rich>=13.0",
     "httpx>=0.25",
+    "typing-extensions>=4.8",
 ]
 
 [project.optional-dependencies]

{capauth-0.3.4 → capauth-0.3.6}/scripts/provision_agent_profiles.py

@@ -71,20 +71,30 @@ DEFAULT_AGENTS = [
 # ---------------------------------------------------------------------------
 
 
-def _load_cluster() -> dict:
-    """Return cluster.json contents or a safe default."""
+def _load_cluster() -> dict | None:
+    """Return cluster.json contents, or None when absent/unreadable.
+
+    No fabricated default: inventing an operator/realm here once wrote
+    ``<agent>@chef.skworld`` FQIDs into identity.json on hosts that were
+    never part of that cluster. Callers must tolerate None (fqid omitted).
+    """
     for p in [Path("/etc/skcapstone/cluster.json"), SKCAPSTONE_HOME / "cluster.json"]:
         if p.exists():
             try:
                 return json.loads(p.read_text(encoding="utf-8"))
             except Exception:
                 pass
-    return {"realm": "skworld", "operator": "chef"}
+    return None
 
 
-def _build_fqid(agent: str, cluster: dict) -> str:
-    realm = cluster.get("realm", "skworld")
-    operator = cluster.get("operator", "chef")
+def _build_fqid(agent: str, cluster: dict | None) -> str | None:
+    """Build ``<agent>@<operator>.<realm>``, or None without cluster data."""
+    if not cluster:
+        return None
+    realm = cluster.get("realm")
+    operator = cluster.get("operator")
+    if not realm or not operator:
+        return None
     return f"{agent}@{operator}.{realm}"
 
 
@@ -129,11 +139,16 @@ def _update_identity_json(
     identity_path: Path,
     agent: str,
     capauth_uri: str,
-    fqid: str,
+    fqid: str | None,
     fingerprint: str | None,
     dry_run: bool,
 ) -> None:
-    """Write or merge dual-URI fields into identity.json."""
+    """Write or merge dual-URI fields into identity.json.
+
+    ``fqid`` is written only when resolvable from cluster.json; when the
+    cluster is unknown it is left untouched rather than overwritten with a
+    fabricated or null value.
+    """
     existing: dict = {}
     if identity_path.exists():
         try:
@@ -144,7 +159,8 @@ def _update_identity_json(
     updated = dict(existing)
     # Always set these canonical fields
     updated["capauth_uri"] = capauth_uri
-    updated["fqid"] = fqid
+    if fqid is not None:
+        updated["fqid"] = fqid
     if fingerprint:
         updated["fingerprint"] = fingerprint
     # Ensure core fields are present