Skip to main content

Documentation

Methodology

How the controls catalogue is maintained

Every control in the catalogue is extracted directly from the underlying spec and committed as a YAML entry under packages/controls/data/ in the open-source repository. The full schema, the field reference, and the step-by-step flow for adding new controls or automated tests live in CONTRIBUTING.md on GitHub.

Per-entry, the YAML record carries the canonical id (e.g. EAA-5.2.10.1-04), the spec source citation (document, version, clause, page), the requirement level (shall / should / may), the applicable tiers, the applicable profiles, the role(s) it binds, the kinds of evidence needed to evaluate it, the verbatim spec text, and a hand-written plain-English explanation.

Spec text is reproduced verbatim and is the source of truth. The plain-English field is editorial and gets refined over time; controls whose plain-English is still being drafted are explicitly marked TODO.

When the underlying spec revises, every affected entry gets its version field bumped and the spec text and clause reference updated. Reviews are tracked in commits; the catalogue's git history is the audit trail.

Spec version policy

The catalogue tracks the latest published version of each upstream spec as soon as we can. Currently:

  • ETSI TS 119 472-1 v1.2.1. The primary source for the EAA Conformance module's normative requirements.
  • IETF draft-ietf-oauth-sd-jwt-vc. Latest active draft for SD-JWT VC structure and serialisation rules.
  • IETF draft-ietf-oauth-status-list. Latest active draft for the runtime status-list resolver.
  • RFC 7517 / 7519. JWK and JWT base specs, used by structural cnf checks.

When a spec moves from draft to RFC, we re-extract the catalogue entries that cite it and regenerate the bundle. The same version number that we track shows up in every relevant control's spec_source field.

Scope boundaries

The toolkit covers what can be checked from the artefacts an issuer actually produces. Today that means:

  • Structural checks on the SD-JWT VC compact form (claim presence, type, value range, mutex relationships).
  • Runtime resolution of the IETF Token Status List referenced from the credential.
  • Tier-aware behaviour for cross-cutting rules like the shortLived/status mutex.
  • Gap analysis projecting the same evidence to QEAA and PuB-EAA tiers, with both behaviour-aware and catalogue-delta signals.

What the toolkit does NOT do

Several material things are explicitly out of scope today, either because the upstream infrastructure does not exist, or because the scope is bigger than a public free toolkit can carry, or because the check requires evidence beyond what an EAA artefact alone supplies.

  • No cryptographic signature verification. The engine parses the JWS but does not validate the issuer's signature against a trust anchor. Signature verification arrives with the trust-list integration (see roadmap).
  • No notified-body audit. Pass on every implemented check is not the same as a notified-body conformance certificate. Use this toolkit as a regression gate and a pre-flight; for the formal certification step you still need an accredited assessor.
  • No mdoc support yet. Profile selection accepts ISO mdoc but no checks are wired against the mdoc structure today. The placeholder reflects the catalogue surface; runtime coverage follows.
  • No verifier-behaviour checks. Controls that bind the verifier (must consult trust list before accepting; must enforce key binding on presentation) are in the catalogue but require evidence beyond the EAA artefact (verification log, trust list config, presentation log). Those evidence types are on the roadmap.
  • No user-data extraction. The toolkit reads only the structural claims of the credential. It does not surface the subject's personal attributes back to you in the report and never transmits them anywhere.

Calibration against ETSI Plugtests

The reference samples library is named to mirror the ETSI EAA Plugtests SJV-EAA test-case ids (sjv-eaa-1 through sjv-eaa-7 currently). Where ETSI publishes a descriptor (pseudonym, oneTime, ShortLived) the corresponding sample exercises that exact claim. Exact alignment with the Plugtests scoring matrix is a continuous process; the catalogue and the samples are the working surface.

See /reference-samples/ for the live list and per-sample descriptions.

Last reviewed 02/05/2026. All documentation · Back to the Hub ·