Registry stack documentation: machine-readable Markdown.
Index of all pages: https://docs.registrystack.org/llms.txt
Full corpus: https://docs.registrystack.org/llms-full.txt

# Configure OpenCRVS claims

> Copy the OpenCRVS starter, verify its synthetic DCI journey offline, and build Relay and Notary configuration inputs.

import ProjectStarterSequence from '../../../components/ProjectStarterSequence.astro';

Use this guide when a Registry Stack project needs birth-record claims from an OpenCRVS
deployment. Registry Relay owns the Digital Convergence Initiative (DCI) source interaction and
returns only the typed outputs in the compiled consultation. Registry Notary evaluates and
discloses the configured claims from that Relay result.

{/* Evidence: crates/registryctl tests and fixtures under
    tests/fixtures/project-authoring/opencrvs/. */}

## When to use this

Use the starter as a reviewed starting point for an OpenCRVS DCI search journey. The built-in
fixtures are synthetic. They prove the canonical token, key, and search requests, signed response
verification, exact identifier matching, ambiguity handling, output minimization, and claim
evaluation without contacting OpenCRVS, Relay, or Notary.

The starter does not prove compatibility with a particular OpenCRVS deployment. Record that
evidence separately before marking a source version verified.

## Before you start

You need:

- A `registryctl` build with Registry Stack project authoring commands
- A shell and a text editor
- The reviewed OpenCRVS DCI endpoint, sender and receiver identifiers, registry profile, and
  signing-key policy for the target deployment

Keep OAuth credentials and signing keys out of authored files, fixtures, commands, and test
output.

## Copy the OpenCRVS starter

Create the project workspace:

```sh
registryctl init --from opencrvs-dci --project-dir opencrvs-project
```

The result confirms the initialized project and next command:

```text
Initialized Registry Stack project "fictional-civil-registry".
  Directory: opencrvs-project
  Starter: opencrvs-dci (Registry Stack 0.13.0)
  Starter content: matches bundled digest
  Editor support: VS Code and Zed (opencrvs-project/.registry-stack-editor/manifest.json)

Next:
  cd opencrvs-project
  registryctl test --project-dir .
```

The project contains one combined topology. Relay owns the OpenCRVS integration and consultation.
Notary owns the evidence service, claims, disclosure policy, and optional credential profiles.

## Run the canonical starter sequence

Use the focused trace and watch smoke before adapting the OpenCRVS profile. The complete fixture
test remains offline and uses only synthetic token, key, and DCI search interactions.

<ProjectStarterSequence starter="opencrvs-dci" />

## Prove the synthetic journey

Run every fixture without a network connection:

```sh
registryctl test --project-dir opencrvs-project
```

The human-readable report starts with:

```text
PASS: <passed>/<total> fixtures passed
```

The match fixture proves the exact identifier and minimized birth-record outputs. The no-match and
ambiguity fixtures prove that Relay does not choose a record when the source result is absent or
non-unique. Derived checks reject malformed signatures, unexpected response shapes, excessive
data, and source work before authorization.

## Adapt the project contract

Review and update these surfaces:

1. In `registry-stack.yaml`, set the registry id, service purpose, caller scopes, consultation
   input mapping, claims, disclosure modes, and credential profiles.
2. In `integrations/birth-record/integration.yaml`, set the OpenCRVS product evidence, allowed
   source version, DCI endpoint path, sender and receiver identifiers, registry and record types,
   selector mapping, outputs, and limits.
3. In `integrations/birth-record/adapter.rhai`, keep the source calls and response handling within
   the declared method, path, origin, output, and limit authority.
4. In `integrations/birth-record/fixtures/`, replace the fictional observations with wholly
   synthetic examples of the reviewed request and response contract.
5. In `environments/<environment>.yaml`, bind the private source, OAuth, trust, Relay workload,
   caller, issuance, and deployment settings through secret references.

`source.product` and `source.versions` are interoperability evidence. They do not enable DCI,
Rhai, or another executor. The script capability remains available for any source product whose
reviewed integration needs bounded multi-request adaptation.

## Check and build the combined topology

Validate the adapted project and inspect its redacted plan:

```sh
registryctl check \
  --project-dir opencrvs-project \
  --environment local \
  --explain
```

The human-readable report marks the project `valid`. Review the fixed source authority, required
caller scopes, consultation input mapping, output projection, claims, disclosure modes, and required
review classes. Add `--format json` only for machine processing.

Generate deterministic unsigned inputs for both products:

```sh
registryctl build \
  --project-dir opencrvs-project \
  --environment local
```

The human-readable report starts with `Built Registry Stack project` and identifies the output
directory. The output has separate Relay and Notary Config Bundle input directories under
`.registry-stack/build/local/private/`. It contains secret references, not secret values. Package,
sign, verify, and activate each product input through that product's Config Bundle workflow.

## Verify the boundary

Before deployment approval, confirm:

- Only Relay has source origin, credential, token, and source-trust bindings.
- Notary has a Relay workload binding for registry-backed claims and no direct OpenCRVS connector.
- The source product and version do not select the script capability.
- Each fixture proves the canonical source request and a minimized typed result.
- The generated review record identifies every semantic and operator-security review required by
  the adapted project.

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| A fixture request differs from the trace | The expected DCI interaction does not match the compiled integration. | Correct the integration or update the wholly synthetic interaction proof. |
| Signature verification fails | The synthetic response, key set, algorithm, or configured key policy is inconsistent. | Regenerate only synthetic fixture evidence from the reviewed contract. |
| A source response is ambiguous | More than one record matches the exact identifier. | Correct the source data or strengthen the reviewed selector contract. |
| Notary contains an OpenCRVS source credential | Source authority crossed the Relay boundary. | Remove the Notary binding and bind the credential only to the Relay integration environment. |
| A product or version change enables script execution | Runtime dispatch is coupled to interoperability metadata. | Keep `capability.script` explicit and treat product and version only as evidence. |

## Next

- Return to [Author an HTTP Registry Stack project](../author-registry-project/) for the complete
  fixture, review, and unsigned-build workflow.
- Use [Configure a script source adapter](../configure-project-script-adapter/) to review the
  product-neutral Rhai host boundary.
- Read [Integration patterns](../../explanation/integration-patterns/) for the Relay and Notary
  topology around a domain system.