trust-graph

name	trust-graph
description	Pod-side certification-edge trust-graph admission with the opt-in cert-graph (sparq-trust) + trust-graph (sparq-solid) cargo features, both default-OFF: anchor trust in a certifier (a framework operator / Trusted-List authority) via a Control-gated trust:TrustRule, then let the depth-bounded, attenuation-only, fail-closed closure (derive_effective_rules) turn that certifier's signed trustx:Certification edges into derived rules the UNCHANGED admission gate consumes — so a pod admits facts from issuers the certifier vouches for, never wider than the certifier's own authority. Use when access should follow certified-issuer attestations rather than a controller-enumerated agent list; covers the anchor-rule TTL shape, the certification-bundle shape, the six EdgeRejection fail-closed reject reasons, and the PodStore wiring. RESEARCH prototype — no privacy/unlinkability claim, ZK estate externally unaudited (sq-qhy4).
license	MIT
metadata	{"version":"0.1.0","homepage":"https://github.com/jeswr/sparq"}

sparq trust-graph — certification-edge admission (pod-side closure)

The certification-edge layer answers: "my pod anchors trust in a certifier (a government framework operator, a Trusted-List registrar) — may it therefore admit facts from an issuer that certifier has certified, without me enumerating that issuer myself?"

sparq_trust::graph::derive_effective_rules (opt-in cert-graph feature on sparq-trust, default-OFF) runs a depth-bounded (v1: depth-1), attenuation-only, fail-closed closure over signed trustx:Certification edges. It is pure pre-processing: it produces the Vec<TrustRule> that the UNCHANGED admission gate (sparq_trust::admit) then consumes exactly as it consumes a hand-authored policy.

  direct_rules (Control-gated trust:TrustRule anchors)   signed trustx:Certification edges
                                  │                            │
                                  ▼                            ▼
  ┌────────────────────────────────────────────────────────────────────┐
  │  derive_effective_rules   (opt-in `cert-graph`, default-OFF)       │
  │  depth-1 · attenuation-only · fail-closed                          │
  │  every derived rule ⊆ (anchor ∩ cert scope ∩ validity window)      │
  └────────────────────────────────────────────────────────────────────┘
                                  │  effective_rules = direct_rules ++ derived
                                  ▼
  ADMISSION gate (sparq_trust::admit, UNCHANGED) ─→ auth grants in <urn:sparq:auth>
                                  (pod wiring: sparq-solid `trust-graph`, default-OFF)

What this is — and is NOT (honest scope, read first)

• RESEARCH prototype, default-OFF. Every flag involved is opt-in and default-OFF (cert-graph on sparq-trust, trust-graph on sparq-solid, solid-authz-trust on sparq-server). With the features off, the crates build byte-identically to plain WAC/ACP today — strict additivity is a design property (G6, research/solid-trust-graph-authz-design.md §2.2).
• NO privacy / unlinkability / anonymity claim. Admission is the clear path: the credential is admitted in the clear and the holder binding authenticates a clear WebID. The ZK estate this layer shares a signature primitive with has no external accredited-cryptographer sign-off (open audit gate sq-qhy4), and sparq-mpc is honest-majority semi-honest only. Nothing in this skill is a production security guarantee.
• Framework trust is ANCHORED, not proven. A trustx:Certification bottoms out in a trust anchor you chose, not cryptography (design §7.2). The certifier's own key is still operator-/DID-asserted — the live upstream forgery vector (D′, sq-pfae.3). The closure defeats broadening and forged-edge escalation given honest anchor keys; it does not close the key-trust gap above it.
• Attenuation-only is the HARD invariant. A derived rule that grants an issuer authority its certifier does not hold is a privilege escalation, not a bug to paper over. Where narrowing cannot be proven (undecidable SHACL-shape containment), the edge contributes nothing.

When to reach for trust-graph vs plain WAC/ACP

• Plain WAC/ACP (skills/access-control/SKILL.md) — the controller can enumerate the agents/clients/issuers directly (acl:agent, ACP matchers). No sparq-trust needed.
• Trust-graph admission, direct anchors only — access should follow an externally-attested fact ("age over 18, said by an issuer I trust for age statements"), and you can enumerate each trusted issuer yourself as a trust:TrustRule. That path is documented in skills/access-control/SKILL.md (the trust-graph feature's admission stratum) — this skill does not repeat it.
• The certification-edge closure (this skill) — you anchor a certifier (framework operator / Trusted-List) rather than each issuer, and want issuers it certifies to be admitted transitively (depth-1), automatically narrowed to what the certifier itself may confer. The trustx:trustsFramework mode of the trust-requirements vocabulary ("admit issuers certified under this framework, subject to scope conformance") is what this closure operationalises pod-side.

Feature flags (all default-OFF, opt-in — the core stays lean)

# The closure itself (sparq_trust::graph): derive_effective_rules, explain_edge,
# Certification, CertScope, EdgeRejection. Implies the trustx: framework-vocab module.
sparq-trust = { path = "crates/sparq-trust", features = ["cert-graph"] }

# Pod-side wiring: PodStore admission-install methods over <urn:sparq:auth>.
sparq-solid = { path = "crates/sparq-solid", features = ["trust-graph"] }
# + DID-resolved issuer keys (trust:issuerDid) instead of operator-asserted hex:
sparq-solid = { path = "crates/sparq-solid", features = ["trust-graph-did"] }

The HTTP surface (sparq-server) exposes the same closure behind its own opt-in solid-authz-trust feature: the request's JSON trust block may carry a "certifications" array (wire schema in crates/sparq-server/src/solid_authz.rs), and the handler runs derive_effective_rules(..., depth_bound = 1) ahead of admission, reporting certGraphDerived in the decision JSON.

The anchor rule — trust:TrustRule is the ceiling

Anchors are the trust ROOT: only a certifier that already appears in the Control-gated policy (as a rule trust:source with the matching key) can confer anything. The policy graph is parsed by sparq_trust::parse_policy (possession of a ControlGate is the authoring channel — same discipline as .acl/.acr). Reified authoring form (namespace trust: = https://sparq.dev/ns/trust#):

@prefix trust: <https://sparq.dev/ns/trust#> .
@prefix xsd:   <http://www.w3.org/2001/XMLSchema#> .

[] a trust:TrustRule ;
  trust:source      <https://gov.example/framework> ;   # the certifier's identity IRI
  trust:issuerKey   "a1b2…" ;                           # its verification key, hex (or trust:issuerDid)
  trust:forPredicate <https://schema.org/age> ;         # statement-type CEILING (desugars to
                                                        # a single-predicate trust:forShape)
  trust:scope       <https://pod.example/medical/> ;    # resource/container ceiling
  trust:freshWithin "P30D"^^xsd:duration .              # staleness ceiling

Field-by-field, each is a ceiling the closure can only narrow, never widen:

• trust:source + trust:issuerKey — a certification is anchored only if its certifier IRI and key both match a rule here (trust:issuerDid works too, behind the did / trust-graph-did features).
• trust:forShape / trust:forPredicate — the statement-type ceiling: a SHACL node-shape (a forPredicate is desugared into a single-predicate shape). The derived rule's shape is anchor.shape ∩ cert.scope.
• trust:scope — the resource ceiling. A certification narrows WHO and WHAT-TYPE, never widens WHERE: the derived rule inherits the anchor's resource scope unchanged.
• trust:freshWithin (xsd:duration) — the staleness ceiling: the derived rule's freshness is min(anchor.fresh_within, certification window remaining).

The equivalent claim-level relational form (trust:trustsSourceFor) desugars to the same Vec<TrustRule> — see skills/access-control/SKILL.md for both authoring forms.

The certification bundle — trustx:Certification

A certification is a signed edge: an authority attests that an issuer is certified — under a framework, over a scope, within a validity window. A Trusted-List entry or a DIATF-register entry IS one such edge. The vocabulary (namespace trustx: — the same https://sparq.dev/ns/trust# namespace, machine-readable form in crates/sparq-trust/ontologies/trust/trust-framework.ttl):

@prefix trustx: <https://sparq.dev/ns/trust#> .
@prefix xsd:    <http://www.w3.org/2001/XMLSchema#> .

<urn:example:cert-1> a trustx:Certification ;
  trustx:certifies      <https://issuer.example/dvs> ;      # the vouched-for issuer
  trustx:underFramework <https://gov.example/framework> ;   # the trustx:Framework
  trustx:scope          trustx:AnyServiceScope ;            # or a SHACL shape / rulebook IRI
  trustx:validFrom      "2026-01-01T00:00:00Z"^^xsd:dateTime ;
  trustx:validUntil     "2027-01-01T00:00:00Z"^^xsd:dateTime .

What the closure actually consumes is the sparq_trust::graph::Certification struct — the edge plus the two keys and the certifier's signature:

• certifier / certifier_key — must match an anchor rule's source + issuer_key.
• certified_issuer / certified_key — the derived rule's issuer identity + key. The key is bound into the signed message, so a substituted key breaks the signature.
• scope — CertScope::AnyService (the coarsest, service-level scope — the honest DIATF granularity; imposes no statement-type narrowing of its own, the anchor shape stays the ceiling) or CertScope::Shape(…) (the issuer is certified only for statements matching that SHACL node-shape).
• valid_from_unix_secs / valid_until_unix_secs — the inclusive window.
• signature_hex — the certifier's Schnorr signature over the domain-separated certification_message (domain tag "TRUSTCRT", distinct from delegation-hop / commitment / holder-PoP tags). A graph merely claiming trustx:certifies proves nothing: the signature is CHECKED, never taken on assertion, and it covers the scope + window, so a narrow certification cannot be re-presented broadened.

The closure — derive_effective_rules → the unchanged admit

use sparq_trust::graph::{derive_effective_rules, Certification};
use sparq_trust::policy::TrustRule;

// direct_rules: parse_policy(...) output (the Control-gated anchors).
// certifications: the framework's published register entries, as signed edges.
let effective: Vec<TrustRule> =
    derive_effective_rules(&direct_rules, &certifications, now_unix_secs, 1);
// `effective` = direct_rules (cloned verbatim, in order) ++ surviving derived rules.
// Feed it to sparq_trust::admit exactly like a hand-authored policy — no gate change.

Load-bearing properties (each adversarially tested in crates/sparq-trust/tests/certification_graph_e2e.rs):

• Strict additivity — zero surviving certifications ⇒ the output is direct_rules byte-identical. The closure can only append.
• Depth-bounded — v1 is depth-1: derived rules are never re-used as anchors for a further round; depth_bound = 0 short-circuits to direct_rules verbatim.
• Attenuation-only — every derived rule satisfies derived ⊆ (anchor ∩ cert scope ∩ validity window). Shape containment is target-set-contravariant, conformance-covariant: a cert shape narrows the anchor only when its SHACL selection/target predicates are a subset of the anchor's (targets may only shrink — an extra sh:targetSubjectsOf WIDENS) and its conformance constraints are a superset (constraints may only grow). Anything unprovable fails closed.

Fail-closed reject reasons — EdgeRejection

derive_effective_rules silently drops a rejected edge; explain_edge runs the same gates in the same order and returns why an edge contributed nothing (the adversarial matrix asserts against these). The variants, in gate order:

Variant	The edge is dropped because …
Cyclic	certifier == certified_issuer (self-certification), or the certified issuer already anchors the certifier — a cycle could launder a broadening, and adds no authority. Checked FIRST, before the signature.
NoAnchor	no direct_rules anchor has this certifier's source and matching key — the pod does not anchor this certifier, so it can confer nothing.
SignatureInvalid	the signature is absent, unparseable, or does not verify under the certifier's key over the domain-separated certification_message (a self-asserted / forged edge).
OutOfWindow	the window is ill-formed (valid_until < valid_from) or does not cover now — expired / not-yet-valid; fail-closed on time.
Broadening	the certification scope is NOT provably contained in the certifier's anchor shape — a broadening attempt or an undecidable containment (undecidable ⇒ not contained ⇒ contributes nothing).
OverDepth	depth_bound was 0, or the edge would only be reachable beyond the bound (v1 depth-1: derived rules are never anchors).

Pod-side wiring — sparq-solid (trust-graph feature)

With trust-graph ON, PodStore gains the admission-install methods that put derived grants into <urn:sparq:auth> on top of the unchanged WAC/ACP view (grants only union allows; a trust-graph grant can never drop a WAC/ACP grant). Two install paths — choosing the wrong one is a soundness bug (the sq-xc4y static/dynamic split):

• PodStore::admit_trust_credential_static — the materialise-time path: runs only the session-independent class (admit_static) and installs auth:ConditionalGrants whose holder + freshness are re-checked per request. Use this for a long-lived materialise-once view.
• PodStore::admit_trust_credential_and_materialize (and _with_rule) — the single-request snapshot path: runs the combined gate against one live Session and installs an unconditional grant valid for that request only. Never use it to populate a long-lived view.

Feed effective_rules from the closure to either path as the rules argument; admission itself never errors — a credential that fails any gate simply admits nothing (fail-closed, default-deny).

Cross-references

• skills/access-control/SKILL.md — the WAC/ACP layer, the admission stratum, both anchor-authoring forms, the TrustStore narrowing model (this skill deliberately does not duplicate it).
• skills/verifiable-credentials/SKILL.md — the standards-interop signed-graph complement; skills/zk-query-proofs/SKILL.md — the (externally unaudited, sq-qhy4) ZK estate.
• crates/sparq-trust/README.md + the sparq_trust::graph module docs — the full invariant discussion; crates/sparq-trust/tests/certification_graph_e2e.rs — the adversarial edge-forgery matrix.
• research/trust-expression-spec.md §3.4 and research/solid-trust-graph-authz-design.md — the design records (epic sq-pfae, issue #940).