Package a lookup over a registry

If your institution keeps records in a Base Registry Engine (BReg) registry, Evidence can use one of its lookup routes as a fixed source and sign a narrow answer about the record it finds. You start a new project here, not one from either first tutorial. Evidence inherits none of the registry’s authorization: the registry decides what the source credential reads, and Evidence decides who may ask.

Outcome

A checked Evidence candidate with two Sources, three AssertionDefinitions, and 35 synthetic fixture cases.

Time

About 20 minutes after installing matching binaries

Level

Offline authoring with synthetic data

Prerequisites

The BReg and Evidence components installed for rstackA shell, tar, yq version 4, and an editorThe downloaded BReg and Evidence teaching archive

Unpack the teaching registry

Download the BReg and Evidence teaching files into a fresh working directory as breg-evidence-starter.tar.gz, then unpack them and check the registry:

mkdir teaching-inputs
tar -xzf breg-evidence-starter.tar.gz -C teaching-inputs
cp -R teaching-inputs/registry ./registry
rstack breg check ./registry

The registry has one Record type, record, with two unique selectors, by-code and by-registration-number. Its evidence-source access profile may only look records up, and cannot read label. The two breg.access.profile-unrestricted-rows warnings are expected: both profiles set rowBoundaries: unrestricted.

The archive also holds offline-starter, a complete Evidence project, and starter, a fragment of assertion definitions. Start the project from the first:

rstack evidence init ./evidence --starter ./teaching-inputs/offline-starter --profile local
rstack evidence test ./evidence --target ./evidence/local-target.yaml

PASS: fixtures/extract-record-active.yaml (13 cases)

Those 13 cases prove a SQLite-extract Source, not registry access.

Export the lookup as a source

The registry writes the source description, so the lookup Evidence calls is the one the registry reviewed:

rstack breg generate evidence-source ./registry \
  --access-profile evidence-source --record-type record \
  --selector by-code --selector by-registration-number \
  --fields status --source-id registry-status --connection registry \
  --authentication oauth2-private-key-jwt \
  --output ./registry-status-export

It reports Generated 9 artifacts. The export names the profile, both selectors, and the status fact, and grants no registry authority. Asking for label is refused with breg.evidence-source.refused: the export describes only what the registry already lets that profile see. --authentication oauth2-private-key-jwt makes the export’s pack declare the flow the target binds below; the pack and the target must name the same authentication type, or evidencectl check refuses them.

Import it into the project:

rstack evidence source import ./registry-status-export --project ./evidence

{
  "affectedDefinitions": [],
  "application": "accepted",
  "conflicts": [],
  "sources": ["registry-status"]
}

The import checks every artifact’s checksum, then adds the registry-status Source, its selector profiles, and two Functions. It adds no assertion definition and no caller grant: the registry’s profile does not become an Evidence permission. For a local registry with a stopped development session, rstack evidence source add does both steps, driving the BReg tooling selected from the same managed release.

Add the assertion definitions

Copy the fragment’s Functions and fixtures, then merge its definitions with yq version 4:

cp teaching-inputs/starter/functions/*.rhai evidence/functions/
cp teaching-inputs/starter/fixtures/*.yaml evidence/fixtures/
yq --inplace '
  .functions += load("teaching-inputs/starter/definitions.yaml.fragment").functions
  | .assertionDefinitions += load("teaching-inputs/starter/definitions.yaml.fragment").assertionDefinitions
' evidence/evidence.yaml
yq '.assertionDefinitions | keys' evidence/evidence.yaml

- extract-record-active
- record-active
- record-status-pair

record-active derives one boolean and record-status-pair the active and retired pair, both through the imported Source. Who may request them is Evidence’s grant ceiling and authority, reviewed in this project, not anything the registry granted.

Bind the registry connection and package

Create a target for the project:

rstack evidence target new ./configured-target --local --project ./evidence

Created Evidence target ./configured-target
Source connections declared from local-target.yaml: record-status-extract
Source extracts declared from local-target.yaml: record-status-extract

The new target already carries what the project’s local-target.yaml declares: the offline starter’s record-status-extract connection and the extract file it reads. Bind the registry connection the export named, with its registry endpoint. Its credential is the source client’s own, issued by the registry’s identity provider; an Evidence caller never holds it:

configured-target/target.yaml

connections:
  record-status-extract:
    endpoints: {}
  registry:
    endpoints:
      registry:
        origin: http://127.0.0.1:8090
        authentication:
          type: oauth2-private-key-jwt
          tokenEndpoint: http://127.0.0.1:8091/oauth2/token
          clientIdRef: secret:file/registry-client-id
          clientAssertionKeyRef: secret:file/registry-client-key
          clientAssertionAudience: http://127.0.0.1:8091
          scope: registry:evidence:lookup
          maximumCacheSeconds: 60

Fixtures supply recorded responses, so nothing contacts these endpoints; bind the real origin, issuer, audience, scope, and secrets before live use. Prove the project and package it:

rstack evidence test ./evidence --target ./configured-target
rstack evidence package ./evidence --target ./configured-target --output ./candidate

4 passed, 0 failed (35 cases evaluated)

The package report lists the secrets to provision, the two registry client secrets among them.

Once the registry is deployed, check what the source credential reaches

Fixtures cannot show what a live credential reaches. Run this check against your deployed registry once it serves this project, and before Evidence takes traffic, calling it as Evidence will, with the source client’s token. Ask your identity operator for an owner-only source-authorization.header file containing one complete Authorization: Bearer <token> line for the source client, kept outside the candidate. Put the synthetic selector in source-lookup.json:

{"selector":"by-code","values":{"code":"SYNTHETIC-ACTIVE"}}

Look the record up through the route the export names:

rstack breg api '/v1/records/records:lookup?accessProfile=evidence-source&$select=code,status' \
  --url https://registry.example.invalid \
  --header @./source-authorization.header \
  --input source-lookup.json \
  --output source-lookup-response.json

A match exits 0 with one record, limited to code and status; read its UUID from data.recordIdentifier. A non-success status leaves the problem body in the output file and makes the command exit non-zero.

Then ask for the same record through the operator profile, which the source client does not hold. Replace <recordIdentifier> with the UUID:

rstack breg api '/v1/records/records/<recordIdentifier>?accessProfile=operator' \
  --url https://registry.example.invalid \
  --header @./source-authorization.header \
  --output source-refusal.json

This one must fail with HTTP 404 and the problem resource.not_found, which is also how the registry answers a missing record, so ask the registry operator to confirm with their own credential, in their own workspace, that the record exists under operator. Read refusals lists these answers. If the request succeeds, keep traffic off and correct the source client or the profile before you retry.

Keep the two reviews separate

A changed selector, fact, or profile needs a fresh export, a reviewed rstack evidence source diff and source update, and a new package. How Evidence works explains the split.

Next

Prove a Registry Evidence project