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

Matching bregctl, evidencectl, and evidence binaries on PATHA 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
bregctl 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:

evidencectl init ./evidence --starter ./teaching-inputs/offline-starter --profile local
evidencectl 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:

bregctl 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 \
  --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.

Import it into the project:

evidencectl 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, evidencectl source add does both steps, driving the bregctl of the same version on your PATH.

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:

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

Created Evidence target ./configured-target

Bind the registry connection the export named. 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: {}
connections:
  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:

evidencectl test ./evidence --target ./configured-target
evidencectl 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.curl file holding a short-lived authorization header 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:

curl --silent --show-error --fail-with-body \
  --config ./source-authorization.curl \
  --header 'Content-Type: application/json' \
  --data-binary @source-lookup.json \
  'https://registry.example.invalid/v1/records/records:lookup?accessProfile=evidence-source&$select=code,status' \
  --output source-lookup-response.json --write-out 'HTTP %{http_code}\n'

A match answers HTTP 200 with one record, limited to code and status; read its UUID from data.recordIdentifier.

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

curl --silent --show-error --fail-with-body \
  --config ./source-authorization.curl \
  'https://registry.example.invalid/v1/records/records/<recordIdentifier>?accessProfile=operator' \
  --output source-refusal.json --write-out 'HTTP %{http_code}\n'

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 evidencectl source diff and source update, and a new package. How Evidence works explains the split.

Next

Prove a Registry Evidence project