# X-TA-001 Test Run Attestation

**Status: proposal.** This page describes a proposed design. The conformance harness and test suites it refers to are not yet released, the field names may change, and the declaration text awaits legal review. Nothing on this page is a certification programme.

A Test Run Attestation (TRA) is a signed statement by an implementer that a named version of its implementation was run against a named version of an OAE test suite, with a stated result. The implementer signs it with its own key. Anyone can check it: a lender, a valuation firm, a condition provider or another implementer.

## What a TRA is and is not

| A TRA is | A TRA is not |
| --- | --- |
| The implementer's own claim about one test run, under its own signature and a named declarant | A certificate, approval or endorsement by Realworld or by OAE |
| Bound to an exact suite release by digest, so the suite cannot be swapped | Evidence that the implementer's valuations, inspections or credentials are correct |
| Verifiable offline from public inputs | A listing: Realworld publishes no list of implementers or TRAs |
| Valid for a limited scope and period | A recipient's acceptance decision. Acceptance is recorded separately by the recipient |

Signature is not authority, truth, reliance or permission. A TRA says who claims what about which test run; it does not say that the claim is true beyond what the suite checks.

## Roles

| Role | Signs | Responsibility |
| --- | --- | --- |
| Suite maintainer | Test suite releases and the suite version manifest only | Publishes profiles, rules and test vectors; never signs a statement about an implementer |
| Implementer | The TRA, with a key registered under its trust framework entry | Runs the harness on the implementation it declares and publishes the TRA |
| Declarant | The declaration inside the TRA, through the implementer's signature | A named officer of the implementer, in a role the implementer has delegated for this purpose |
| Trust framework | Its own directory and status records | States whether the implementer's entity and key are registered and active |
| Any verifier | Nothing | Checks the TRA with the reference verifier or an independent implementation |

## How it works

```mermaid
flowchart TB
  subgraph MAINT["<br>Suite maintainer"]
    direction TB
    SUITE["Signed suite release<br/>profile + vectors + rules"]
    MAN["Signed version manifest<br/>current, supported, deprecated"]
  end

  subgraph IMPL["<br>Implementer (runs locally)"]
    direction TB
    HAR["Conformance harness<br/>CLI, container or MCP"]
    SYS["Implementation under test<br/>issuer or verifier"]
    REP["Run report<br/>checks passed and failed"]
    TRA["Test Run Attestation<br/>signed with implementer key"]
    HAR --> SYS --> REP --> TRA
  end

  WK["Implementer's own website<br/>/.well-known/oae/tra/"]
  TF["Trust framework directory<br/>entity and key status"]
  VER["Any verifier<br/>lender, firm or peer"]
  RES["Verification result<br/>X-VR-001"]

  SUITE --> HAR
  MAN -.-> HAR
  TRA --> WK
  WK --> VER
  TF --> VER
  MAN -.-> VER
  VER --> RES

  class MAINT,IMPL rwGroup
  class SUITE,MAN,HAR,SYS,REP rwOutline
  class TRA,RES rwSolid
  class WK,TF,VER rwSoft
```

1. The suite maintainer publishes a signed suite release and a signed version manifest. They contain profiles, rules and test vectors. They name no implementer.
2. The implementer downloads the release, checks its signature and runs the harness locally against its own implementation. No Realworld service is involved and no data leaves the implementer's environment.
3. The harness produces a run report and a TRA draft that binds the suite digest, the implementation build and the result.
4. A named declarant confirms the declaration, and the implementer signs the TRA with its key.
5. The implementer publishes the TRA on its own website at a well-known path and may also send it directly to lenders or partners.
6. Any party verifies the TRA: the signature, the implementer's status in its trust framework, the suite digest and the TRA's scope and validity.

## Verification

```mermaid
flowchart TB
  A["1 Signature<br/>valid for the key"] --> B["2 Key and entity<br/>active in trust framework"]
  B --> C["3 Suite digest<br/>matches a signed release"]
  C --> D["4 Suite version<br/>not deprecated"]
  D --> E["5 Scope and period<br/>not expired"]
  E --> F["6 Declarant role<br/>delegated by implementer"]
  F --> G["Result<br/>ALLOW or DENY with reasons"]

  class A,B,C,D,E,F rwOutline
  class G rwSolid
```

| Step | Check | If it fails |
| --- | --- | --- |
| 1 | The TRA signature verifies with the stated key | DENY |
| 2 | The key and the implementer's entity are registered and active in the named trust framework, at signing time and now | DENY, or UNKNOWN if the framework cannot be reached |
| 3 | `suite.digest` equals the digest of a suite release signed by the suite maintainer | DENY |
| 4 | The suite version is supported according to the signed version manifest | DENY for a withdrawn version; a deprecated version is reported as such |
| 5 | The TRA is within its validity period and its status entry is not revoked | DENY |
| 6 | A delegation statement on the implementer's domain names the declarant's role | Declaration reported as UNVERIFIED |

The result follows the [X-VR-001 Verification Result Contract](../shared/verification-result-contract.md). Unknown evidence never becomes a pass.

Because step 2 uses the trust framework's own records, a TRA stops verifying when the framework suspends the implementer or revokes the key. No one has to maintain a separate list.

Any implementer can therefore verify any other implementer's TRA, using the same public inputs.

## Fields

The TRA is carried as an SD-JWT VC (see [X-BD-001 SD-JWT VC Binding](../shared/sd-jwt-vc-binding.md)). The proposed claims are:

| Field | Meaning |
| --- | --- |
| `vct` | Credential type. Placeholder: `internal-placeholder:unregistered-namespace:credential:test-run-attestation:0-proposal` |
| `issuer` | The implementer, identified as in its trust framework entry |
| `trust_framework` | The framework and entry under which the signing key is registered |
| `suite` | Suite id, version and digest of the signed release used |
| `profile` | Profile id and version tested, for example V-PP-001 0.4.0-draft |
| `role_tested` | The role of the implementation under test: issuer, presenter or verifier |
| `implementation` | Product name, version and build digest |
| `harness` | Harness version and digest |
| `run` | Run date, mode (sandbox keys only), configuration digest |
| `result` | Overall outcome, counts of checks passed and failed, ids of failed checks |
| `report_digest` | Digest of the full run report; the report itself is not embedded |
| `pre_reveal` | Optional: the build digest recorded before a new test set was revealed, and its result |
| `declaration` | Declarant role and name, declaration text id and version, scope |
| `delegation_ref` | Location of the implementer's delegation statement for the declarant role |
| `valid_from`, `valid_until` | Validity period |
| `status` | Token Status List entry, controlled by the implementer |

## Declaration

The declaration is a short, versioned statement confirmed by the declarant, for example: "I confirm that this test run was performed on the implementation identified above, without modification for the purpose of the test, and that the result is reported as produced by the harness."

Its scope is fixed: this key, this suite major version, at most twelve months. The exact wording, its legal effect and the party it is addressed to are subject to legal review before any TRA is relied on.

## Signing key

The implementer signs with a key registered under its trust framework entry. Two options are under consideration:

- the same key it uses to sign credentials;
- a separate key, registered under the same entry for attestations only. This keeps the two kinds of statement apart and limits the effect of a key compromise.

In both cases the key is bound to the implementer's entity in the framework. Production keys are never used inside the harness; test runs use sandbox keys.

## Publication

- The implementer publishes the TRA at `https://<implementer-domain>/.well-known/oae/tra/<suite-id>-<version>.json` (path proposed), together with the delegation statement for the declarant role.
- The suite maintainer publishes only the discovery rules and the suite releases. It does not publish, sign or curate any list of TRAs or implementers.
- Any third party may build an index from public TRAs. That index is its own product and makes no statement on behalf of the suite maintainer.

### Example: a lender checks a valuer

The names and domain below are illustrative.

1. Valuer A runs the harness against OAE Valuation Profile Suite v1.2, signs the TRA with its own registered key and publishes it at `https://valuer-a.example/.well-known/oae/tra/valuation-suite-1.2.json`.
2. Lender Y is considering Valuer A for its panel. It does not ask Realworld, and there is no Realworld list to consult.
3. Lender Y fetches the TRA from Valuer A's domain, or receives it from Valuer A directly.
4. Lender Y checks it with the reference verifier library or its own implementation: Valuer A's signature and key status in its trust framework, the suite digest against the signed suite release, the result, the validity period and the declarant's delegation.
5. Lender Y decides for itself whether to accept Valuer A, and records that decision on its own side.

Realworld publishes only the specification: where a TRA is found and how it is checked.

## Lifecycle

- **Expiry:** at `valid_until`, at most twelve months after the run.
- **New major suite version:** a new run and a new TRA are needed.
- **Withdrawal:** the implementer revokes the TRA through its status entry.
- **Framework action:** if the framework suspends the entity or revokes the key, verification fails automatically.
- **Suite withdrawal:** a TRA against a withdrawn suite version no longer verifies; a deprecated version is reported as deprecated.

## Naming

"Attestation" is also a defined term in eIDAS 2. If that causes confusion, this record may be renamed "Test Run Record". How the OAE name may be cited in a TRA is set out in [Name and brand use](../name-and-brand-use.md).

## Implementation status

Proposal only. The harness, the test suites and this record format are not released. No TRA has been issued or verified outside internal testing.

## Related documentation

[X-VR-001 Verification Result Contract](../shared/verification-result-contract.md) · [X-BD-001 SD-JWT VC Binding](../shared/sd-jwt-vc-binding.md) · [Licensing and use](../licensing.md) · [Name and brand use](../name-and-brand-use.md)
