capauth 0.3.1__tar.gz → 0.3.2__tar.gz

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

@@ -8,6 +8,68 @@ All notable changes to `capauth` are documented here. The format is based on
 
 ### Added
 
+- **`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
+  requirement with no supported constructor. A downstream had to reconstruct the
+  challenge from capauth's source (derive the fingerprint with
+  `fingerprint_for`, canonicalize the subject with `canonical_subject`, assemble
+  `verified_challenge` over exactly those two) and get all three right, or emit a
+  signature that fails identically to a forged one. skchat did it by hand, with a
+  comment saying "capauth has no public helper for this today; if it grows one,
+  delete this and call it."
+  - `build_verified_proof(pubkey, *, private_key, passphrase="", subject=None)` —
+    signs the `verified` challenge with the device's OWN key.
+  - `build_attested_proof(pubkey, *, operator_pubkey, operator_private_key,
+    passphrase="", subject=None)` — an operator vouching for a device it does not
+    hold the private key of.
+  - `enrollment_challenge(pubkey, *, subject=None, mode="verified")` — the
+    challenge bytes derived from the PUBLIC key alone. No secret is involved and
+    none is disclosed, so a server can hand these to a client whose WebCrypto
+    device key is non-extractable and let it sign them.
+  - `EnrollmentProof` — frozen, and implements the mapping protocol, so it
+    splats into `enroll_device` with no massaging:
+    `enroll_device(pub, scopes, mode="verified", subject=subj, **proof)`. It
+    yields only the evidence kwargs the claimed mode requires, never both sets.
+  - `ProofSigningError(PairingError)` — signing failure RAISES, in the same
+    spirit as `TokenSigningError`. An unsigned or empty proof is never returned.
+  - **It is a constructor, not a bypass.** The verifier is untouched, and is in
+    fact called on this module's own output before that output is returned (the
+    round trip is a structural property, not a hope). Every function signs with a
+    private key the CALLER supplies: presenting a proof for a key you do not
+    control is impossible by construction, because the signature IS the proof.
+    The signing branch is chosen from the device public key alone, using the same
+    `"BEGIN PGP" in key` discriminator `_proof_verifies` uses, so a caller can
+    never pick a weaker verifier for itself. Both PGP-armored keys and skchat's
+    base64 DER SPKI ECDSA P-256 device keys are supported.
+  - Negative controls in `tests/test_enrollment_proof_helper.py` pin that a proof
+    over the wrong subject, over the wrong fingerprint, signed by a different
+    key, replayed across the verified/attested domain separation, or simply
+    absent is STILL refused by the real `enroll_device`. They were verified to
+    catch a real regression by deliberately loosening the check and observing
+    them go red.
+
+- **`$SKCAPSTONE_HOME` now overrides `capauth.pairing.store.default_base_dir()`.**
+  The root was hardcoded to `~/.skcapstone` with no override, so a node that
+  legitimately holds a per-agent key but whose flat
+  `~/.skcapstone/identity/identity.json` declares a different key had no
+  supported way to point capauth at a home it can actually sign from. Precedence
+  matches the `capauth.manifest.shell_home` idiom already in this repo: explicit
+  `base_dir=` (unchanged, still wins), then `$SKCAPSTONE_HOME` when set and
+  non-empty, then `~/.skcapstone`. An empty or whitespace-only value falls back
+  to the default rather than resolving against the cwd. Exported as
+  `capauth.pairing.SKCAPSTONE_HOME_ENV`.
+  - With the variable unset, behaviour is unchanged in every respect.
+  - ⚠ **Setting it moves the PAIRING STORE, not just the identity.** The same
+    function locates the peer registry and its device sidecars, pending
+    enrollments, identity-class assignments, and the capability-token store
+    `decide()` reads. A node pointed at a new home starts with an EMPTY device
+    store and will deny every subject enrolled in the old one for "no enrolled
+    device" until it is re-enrolled there. Nothing migrates, merges, or falls
+    back to the previous location: whether two homes should be reconciled is a
+    separate decision, and a silent merge is how one node's device population
+    quietly becomes another's.
+
 - **`capauth.testing`: the gpg signing test seam, promoted from `tests/conftest.py`
   into shipped, importable code.** Since `0d412ab`, `issue_token` and
   `mint_audience_token` RAISE rather than storing an unsigned token, and
@@ -50,6 +112,51 @@ All notable changes to `capauth` are documented here. The format is based on
 
 ### Fixed
 
+- **An unreadable coordination projection rendered identically to an agent with
+  no collaborators** (coord card `49e9b427`).
+  `capauth.trust.graph._add_coord_agents` reads
+  `~/.skcapstone/coordination/agents/*.json`, a rebuildable PROJECTION of the
+  coordination board, and turns `len(completed_tasks)` into a trust edge weight
+  via `0.3 + 0.05n`. It continued past `json.JSONDecodeError` and `OSError` per
+  file, and skdashboard collapses any exception out of `build_trust_graph` into
+  an empty graph, so a projection that could not be read at all produced zero
+  coord edges, no warning, and the same picture in every output format as a
+  healthy agent that simply has no collaborators. Per-file tolerance is kept (one
+  corrupt file must not blank the trust web), but the failures are now counted
+  and reported:
+  - `capauth.trust.SourceHealth`, a new exported record on `TrustGraph`, with
+    statuses `ok` / `absent` / `degraded` / `unreadable`, file counts, the source
+    path, and a bounded sample of the read errors. `TrustGraph.warnings()` is
+    empty only when every instrumented source was read in full, so an absent edge
+    can once again be read as an absent relationship.
+  - `format_json` gains `sources`, `warnings` and `complete` (this is the dict
+    skdashboard's trust panel already parses), `format_table` gains a Sources
+    section plus an explicit incomplete-graph warning, and `format_dot` draws a
+    red node for a degraded source so a rendered image shows the gap instead of
+    just being smaller.
+  - A JSON payload that parses but is not an object (an error page, an array, a
+    bare `null`) now counts as a failed file. Previously it raised an uncaught
+    `AttributeError` out of `build_trust_graph`, which the caller turned into an
+    empty graph.
+  - The directory listing uses `iterdir` rather than `glob`, because `glob`
+    swallows a `PermissionError` on the directory and returns nothing, reporting
+    an unreadable store as an empty one.
+  - Coord edges now carry `source`, `corroborated: False` and `tasks_claimed`
+    metadata, and the read carries a `# PROJECTION-OK:` marker whose
+    justification is conditional on a verified property: `TrustEdge.strength` is
+    consumed only by renderers (DOT `penwidth`, the ASCII bar, skdashboard's
+    stroke width), never by an authorization path.
+
+  Trust SEMANTICS are unchanged on purpose. The audit (188 of 1,683 claimed
+  completions backed by no store, identity fields describing the rebuilder,
+  Syncthing conflict resolution losing completions in one direction, and no
+  representation of the board's `review` column) and the recommendation to stop
+  deriving a weight from a completion count are in
+  `docs/TRUST_GRAPH_COORD_PROJECTION.md`, for the repo owner to decide. The
+  `0.3 + 0.05n` curve is now named (`COORD_BASE_STRENGTH`,
+  `COORD_STRENGTH_PER_TASK`, `COORD_SATURATION_TASKS = 14`) and locked by a test
+  so any future change to it is deliberate.
+
 - **`verified` enrollment was unprovable for WebCrypto device keys**
   (`inc-c72a9120`). N10's proof check was correct but PGP-only: it verified
   `proof` solely through `capauth.crypto`'s armored-signature backend, while

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: capauth
-Version: 0.3.1
+Version: 0.3.2
 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.1 → capauth-0.3.2}/SOP.md

@@ -383,6 +383,18 @@ verify `POST /capauth/v1/verify` (`:266`), authz decision
 (`:653`). **No `/health` route exists**; `/capauth/v1/status` is the liveness probe
 (that is what the compose healthcheck curls).
 
+**Trust graph.** `capauth.trust.graph.build_trust_graph` is a VISUALISATION, not
+a decision input: `TrustEdge.strength` is read only by the renderers (DOT
+`penwidth`, the ASCII bar, skdashboard's stroke width), and no authorization path
+(`authz.py`, `tokens.py`, `service/`) imports the trust graph at all. One of its
+inputs, the coordination `agents/*.json` projection, is known to be corrupt in
+four measured ways and is read anyway under a `# PROJECTION-OK:` marker whose
+justification depends on that separation holding. Every graph now reports per
+source read health (`ok` / `absent` / `degraded` / `unreadable`) so an unreadable
+input is distinguishable from a genuinely empty one. Audit, the marker's
+conditions, and the proposed weighting change:
+[docs/TRUST_GRAPH_COORD_PROJECTION.md](docs/TRUST_GRAPH_COORD_PROJECTION.md).
+
 Full protocol + claim/token format: [docs/PROTOCOL.md](docs/PROTOCOL.md),
 [docs/CLAIMS.md](docs/CLAIMS.md). Crypto detail: [docs/CRYPTO_SPEC.md](docs/CRYPTO_SPEC.md).
 
@@ -443,8 +455,18 @@ Full protocol + claim/token format: [docs/PROTOCOL.md](docs/PROTOCOL.md),
 **SK = staycuriousANDkeepsmilin 🐧** — *capauth: you are not a user, you are a sovereign.*
 
 <!-- docs-evidence
-verified: 2026-08-15
+verified: 2026-08-16
 checks:
+  - name: the trust graph is still display-only, which is what section 7 and the PROJECTION-OK marker rest on
+    run: ! grep -rqE 'trust\.graph|build_trust_graph|TrustEdge' src/capauth/authz.py src/capauth/tokens.py src/capauth/service/
+  - name: the coord projection read still carries its PROJECTION-OK justification
+    run: grep -qF '# PROJECTION-OK:' src/capauth/trust/graph.py
+  - name: coord edges still declare their count uncorroborated
+    run: grep -qF '"corroborated": False' src/capauth/trust/graph.py
+  - name: the coord weight constants and their saturation point are still recorded, not inline magic
+    run: grep -qxF 'COORD_SATURATION_TASKS = 14' src/capauth/trust/graph.py && grep -qxF 'COORD_BASE_STRENGTH = 0.3' src/capauth/trust/graph.py
+  - name: a degraded source is still reported rather than swallowed into an empty graph
+    run: grep -qF 'def warnings(' src/capauth/trust/graph.py && grep -qF '"unreadable"' src/capauth/trust/graph.py
   - name: both console-script entry points are exactly as section 7 documents
     run: grep -qxF 'capauth = "capauth.cli:main"' pyproject.toml && grep -qxF 'capauth-service = "capauth.service.server:main"' pyproject.toml
   - name: capauth-service still defaults to 127.0.0.1 and port 8420 (section 5 Scenario A)

capauth-0.3.2/docs/TRUST_GRAPH_COORD_PROJECTION.md

@@ -0,0 +1,201 @@
+# The coordination projection as a trust input
+
+**Status:** audit landed, failure visibility fixed, weighting change PROPOSED and
+NOT applied.
+**Audited:** 2026-08-16, against the live fleet coordination store.
+**Owner decision required:** yes. See "Recommendation to the repo owner" below.
+**Refs:** coord card `49e9b427`, upstream `ebc927c3` (A5.1), `7dd497bc`.
+
+## 1. What this document is for
+
+`capauth.trust.graph` builds the trust web that `skcapstone trust graph`, the
+skcapstone shell, the `trust_graph` MCP tool and skdashboard's trust panel all
+render. One of its five input sources is the coordination board, and it reads
+that board through a REBUILDABLE PROJECTION rather than through the board's
+store of record.
+
+That read was never audited, because the read lives in capauth and the store
+lives in skcapstone. This document records the audit, states plainly what was
+fixed, and puts the part that changes trust semantics in front of the repo
+owner instead of quietly changing it.
+
+## 2. The read, as it stands
+
+`src/capauth/trust/graph.py::_add_coord_agents` opens every
+`~/.skcapstone/coordination/agents/*.json`, takes `data["agent"]` as the
+collaborator name, and computes:
+
+```
+completed = len(data.get("completed_tasks", []))
+strength  = min(1.0, 0.3 + completed * 0.05)
+```
+
+So a claimed completion count is a direct multiplier on a trust edge weight.
+Fourteen claimed completions saturate the edge at 1.0, and every collaborator
+at or above fourteen is thereafter indistinguishable from every other.
+
+## 3. The audit: four independent ways the count is wrong
+
+All four were measured on the live store on 2026-08-16, not estimated.
+
+1. **1,683 completions are claimed across the agent projections, and 188 of
+   them are backed by no store at all.** Not the coordination event log, not
+   the archive manifest. Each uncorroborated claim inflates a trust edge by
+   0.05.
+2. **The identity fields describe the rebuilder, not the agent.** 106 of about
+   120 agent files share a two-second-wide `last_seen`, and 100 carry the
+   rebuilder's hostname, because `export_to_legacy -> save_agent` restamps
+   `last_seen` and `AgentFile.host` defaults to `socket.gethostname()`. Any
+   freshness or provenance signal on these nodes is an artifact of whoever last
+   ran a rebuild.
+3. **Conflict resolution loses completions in one consistent direction.** All 6
+   Syncthing conflict copies claimed completions that the surviving live file
+   had lost (autopilot 4 versus 0; opus-swarm 5, 11, 22, 5, 11 versus 0), and
+   never the reverse. The live counts are therefore systematically low, and
+   nothing about the surviving file reveals that.
+4. **The projection cannot represent the board's `review` column at all.** 32
+   cards currently disagree between store and projection for structural
+   reasons that no rebuild can fix. A projection that cannot express a state of
+   the thing it projects is not a faithful view of it.
+
+None of this is evidence of an attack. It is evidence that a trust weight is
+computed from a number that is wrong in at least four unrelated ways, and that
+nobody noticed because the reader and the writer live in different repos.
+
+## 4. The aggravating factor, and the thing that was actually fixed
+
+The whole consumer chain was built to hide this. `_add_coord_agents` continued
+past `json.JSONDecodeError` and `OSError` per file, and
+`skdashboard/src/skdashboard/dashboard.py` collapses every exception out of
+`build_trust_graph` into an empty graph so the panel never 500s. The net
+effect: a totally unreadable projection rendered as a graph with zero coord
+edges, which is exactly what a healthy agent with no collaborators renders as.
+Healthy and broken were the same picture, in all three output formats.
+
+That is fixed. `TrustGraph` now carries a `SourceHealth` record per
+instrumented source with four states:
+
+| status       | meaning                                                        |
+| ------------ | -------------------------------------------------------------- |
+| `ok`         | read succeeded. Zero edges means zero relationships.            |
+| `absent`     | the source does not exist on this home.                         |
+| `degraded`   | some records read, some failed. The graph UNDERCOUNTS.          |
+| `unreadable` | nothing could be read. Absence of edges means nothing at all.   |
+
+`TrustGraph.warnings()` is empty only when every instrumented source was read
+in full. The three renderers surface it: `format_json` gains `sources`,
+`warnings` and `complete` (this is the dict skdashboard renders), `format_table`
+gains a Sources section and an explicit incomplete-graph warning, and
+`format_dot` draws a red node for a degraded source so the gap is visible in a
+rendered image rather than expressed as a smaller graph.
+
+Two smaller correctness fixes came with it, both cases where "unreadable" was
+being silently converted into "empty":
+
+- A JSON payload that parses but is not an object (an error page, an array, a
+  bare `null`) is now counted as a failed file. Previously `[1,2,3]` raised an
+  uncaught `AttributeError` out of `build_trust_graph`, which skdashboard then
+  turned into an empty graph.
+- The directory listing uses `iterdir` rather than `glob`, because `glob`
+  swallows a `PermissionError` on the directory and returns nothing, reporting
+  an unreadable store as an empty one.
+
+Per-file tolerance is deliberately KEPT. One corrupt agent file should not
+blank the whole trust web. The change is that tolerated failures are now
+counted and reported instead of being invisible.
+
+## 5. Why the projection is still read at all (the PROJECTION-OK marker)
+
+The marker above `_add_coord_agents` justifies the read for a trust weight
+specifically, and it rests on exactly one property, which was verified rather
+than assumed:
+
+> `TrustEdge.strength` is a DISPLAY quantity and nothing else.
+
+Its only consumers fleet-wide are renderers: DOT `penwidth` in `format_dot`,
+the ASCII bar in `format_table`, and skdashboard's `static/trust.html` stroke
+width and label. No authorization, capability issuance, token gate or policy
+decision in capauth or in any consumer reads it. Nothing under
+`src/capauth/authz.py`, `src/capauth/tokens.py` or `src/capauth/service/`
+imports the trust graph at all. An inflated coord edge draws a thicker line. It
+does not grant anything.
+
+That justification is CONDITIONAL, and the condition is the entire basis of the
+marker. The moment any code path makes an access decision from a coord edge
+weight, this read stops being acceptable and must move to the corroborated
+source. Every coord edge therefore ships with `corroborated: False` in its
+metadata so a future consumer cannot claim it was not told.
+
+## 6. Recommendation to the repo owner
+
+Two of the card's four questions change what trust MEANS, so they are proposed
+here rather than applied. Both are yours.
+
+### (a) Should trust weight derive from a completion count at all?
+
+**Recommendation: no.** Reasoning, in order of weight:
+
+1. **A count measures volume, not trustworthiness.** Fourteen trivial
+   completions produce the same maximal 1.0 edge as years of high-stakes work.
+   The formula rewards task churn, and the fleet's own agents are the ones
+   generating the churn.
+2. **The channel is monotonic and one-directional.** Nothing decays and nothing
+   subtracts. An agent that failed two hundred cards and completed fourteen is
+   rendered as maximally trusted. A trust signal with no way to go down is not
+   measuring trust.
+3. **It is precisely the quantity the store cannot corroborate.** 188 of 1,683
+   claims are backed by nothing (section 3.1). If a count is kept, it must read
+   the union of the coordination event log and the archive manifest, never
+   `agents/*.json`; per card `7dd497bc` an events-only read under-reports by 93
+   percent, so the union is not optional.
+4. **The projection is structurally incomplete** (section 3.4) and its identity
+   fields are rebuild artifacts (section 3.2). It cannot be made faithful by
+   rebuilding it more often.
+
+**Preferred replacement: make the coord edge a PRESENCE edge with a fixed
+strength (0.3), and keep the count as a label and metadata only.** What the
+projection can genuinely support is "these two agents appear on the same
+coordination board". That is a real fact about collaboration, it survives all
+four corruption modes above, and it is all the projection is entitled to
+assert. The human reader still sees "collaborator (7 tasks)" in the label; the
+number simply stops moving a weight. This is also the smallest possible change:
+one constant, no new data source, and the saturation cliff disappears because
+the ramp disappears.
+
+**Second option, if a ramp is wanted:** source it from the corroborated union
+(event log plus archive manifest), make it logarithmic rather than linear so
+volume has diminishing returns, and add recency decay. Note that recency decay
+needs a corroborated timestamp, because `last_seen` on these files is the
+rebuilder's clock (section 3.2). This is real work and it still measures
+volume, so I would only do it if the trust graph is going to become an input to
+something that decides.
+
+**Third option:** keep the status quo plus the marker, which is what this
+change ships as an interim. Acceptable only while section 5 stays true.
+
+### (d) Record or replace `0.3 + 0.05n`
+
+Recorded, not silently kept. The constants are now named in `graph.py` as
+`COORD_BASE_STRENGTH`, `COORD_STRENGTH_PER_TASK` and `COORD_SATURATION_TASKS`
+(14), the saturation point is stated in the code rather than left to be
+discovered, and `tests/test_trust_graph_coord_audit.py` locks the exact curve at
+n = 0, 3, 14 and 200 so that any future change to it is a deliberate, reviewed
+edit rather than a drift.
+
+That test is a lock, not an endorsement. If (a) is accepted, the lock changes in
+the same commit as the formula and the reasoning goes here.
+
+## 7. Follow-ups this change does NOT do
+
+- **skdashboard still collapses every exception into an empty graph** with a
+  `note` field. It now has `sources` and `complete` available in the payload it
+  already parses, and its trust panel should surface both, but that is another
+  repo and another card.
+- **The other file-scanning readers in `graph.py`** (`_add_token_edges`,
+  `_add_feb_edges`, `_add_sync_edges`) still swallow per-file failures without
+  counting them. `SourceHealth` is deliberately general so they can be
+  instrumented the same way. Coord was done first because it is the one whose
+  source is known to be corrupt.
+- **Nothing in this change touches the coordination store or its rebuilder.**
+  The four corruption modes in section 3 are still live. This change makes
+  capauth stop presenting them as fact; it does not fix them.

{capauth-0.3.1 → capauth-0.3.2}/src/capauth/__init__.py

@@ -91,6 +91,7 @@ from .trust import (
     CALIBRATION_FILENAME,
     DEFAULT_THRESHOLDS,
     FORMATTERS,
+    SourceHealth,
     TrustEdge,
     TrustGraph,
     TrustNode,
@@ -191,6 +192,7 @@ __all__ = [
     "has_scope",
     # trust (kernel track M1: moved verbatim from skcapstone)
     "FORMATTERS",
+    "SourceHealth",
     "CALIBRATION_FILENAME",
     "DEFAULT_THRESHOLDS",
     "TrustEdge",
@@ -217,7 +219,8 @@ __all__ = [
 # distribution metadata instead, so this attribute can only ever agree with what
 # pip actually resolved.
 try:  # pragma: no cover - trivial, and the fallback is exercised below
-    from importlib.metadata import PackageNotFoundError, version as _dist_version
+    from importlib.metadata import PackageNotFoundError
+    from importlib.metadata import version as _dist_version
 
     __version__ = _dist_version("capauth")
 except PackageNotFoundError:  # running from a source tree with no install

{capauth-0.3.1 → capauth-0.3.2}/src/capauth/pairing/__init__.py

@@ -66,6 +66,13 @@ from .operator_session import (
     verify_device_signature,
     verify_operator_session,
 )
+from .proof import (
+    EnrollmentProof,
+    ProofSigningError,
+    build_attested_proof,
+    build_verified_proof,
+    enrollment_challenge,
+)
 from .records import (
     MODE_SEVERITY,
     DeviceRecord,
@@ -77,6 +84,7 @@ from .records import (
 from .store import (
     SIDECAR_KEY,
     SIDECAR_VERSION,
+    SKCAPSTONE_HOME_ENV,
     PairingStore,
     default_base_dir,
     fingerprint_for,
@@ -93,6 +101,12 @@ __all__ = [
     "PairingError",
     "verified_challenge",
     "attested_challenge",
+    # supported proof construction (the constructor for the N10 requirement)
+    "build_verified_proof",
+    "build_attested_proof",
+    "enrollment_challenge",
+    "EnrollmentProof",
+    "ProofSigningError",
     # records + modes
     "EnrollmentMode",
     "Enrollment",
@@ -106,6 +120,7 @@ __all__ = [
     "PairingStore",
     "SIDECAR_KEY",
     "SIDECAR_VERSION",
+    "SKCAPSTONE_HOME_ENV",
     "default_base_dir",
     "fingerprint_for",
     # canonical-subject rewrite (card N5)