Skip to main content
Version: Stage 4 - For Public Review

Pilot Design Architecture

1. Executive Summary​

The Pilot Design has been developed by considering how to create a design that meets the principles of design and the "logical model" for the GRID. In the process of developing this design, there were key elements that we wanted to explore, such as a discovery service supported by a decentralised and loosely coupled approach that retains sovereignty and resilience.

We chose to constrain the pilot to the resources already available from the environment of the UNICC Gitlab instance and then to consider how this might work with Registrars and their potential use of gitlab.com and/or github.com repositories.

The intent is that this design is low (to zero) incremental cost for participants and simple enough to enable quick set up and use, but useful enough to help drive real insights into the requirements for the GRID operational design, and for the GRID participants.

At the time of writing, the operational design and implementation of the GRID is expected to be subject to an appropriate UN request and procurement process. The pilot design presented here is intended solely to explore how different approaches might work, not to dictate the chosen design.

The diagram below gives a logical architecture of how the GRID interacts with participant registries.

Logical Model

Logical model of the Global Registry Information Directory

Overview of pilot design​

The GRID Pilot is a decentralized system where "Sovereign Nodes" (pilot representatives of Authoritative Registrars of UN Member States) manage their own data in their own repositories. A UNICC hosted build process "harvests" the data shared by participating registrars, checks that the data has been cryptographically signed by the participant's registered cryptographic key, and then issues a W3C Verifiable Credential (a UNTP Digital Identity Anchor) signed by the GRID.

Key objectives of the pilot are to explore and demonstrate how the design enables the GRID to stay "lightweight" by only harvesting presented metadata, while the Authoritative Registrars maintain control over their data, strictly separating the GRID's role as a Trust Framework from the lifecycle of the data the Registrars issue.

2. Key Design Decisions​

2.1 The Resilient Harvest Model & Separation of Concerns​

The pilot uses a "harvest" approach which simulates a global directory that does not "own" data but collects participant published data and points to the participant's source.

Crucially, this design establishes a strict Separation of Concerns:

  • The Registrar maintains their own metadata and Decentralized Identifier (DID) Document on their own infrastructure, signing their updates with their native repository keys.
  • The GRID Hub acts strictly as the verifier and credential issuer. It proves the data has not been tampered with and issues a UNTP Digital Identity Anchor (DIA) to mathematically anchor the Registrar to the UN trust framework.

This supports the objective that even if the UNICC GRID service fails, the Sovereign Nodes retain their service capability as the primary records of truth.

2.2 Dual-Stack Verification (SSH & GPG)​

For the pilot design, we support two verification methods to accommodate different infrastructure maturity levels to verify data integrity before issuing credentials.

  • Internal Bootstrap Nodes: Verified via SSH Signatures against a local allowed_signers file (Native Git Verify). This is so that we can rapidly make changes to our dummy/trial entries within the GTR Gitlab environment.
  • External Sovereign Nodes: Verified via GPG Signatures against a Keyring (Harvester Verify). These will be representatives of the UN Member State pilot participants.

Design objectives: 1. The Pilot should ensure that issuing and updating an entry's status in a register is a local registrar action that requires zero interaction with the central GRID Hub. Only a change in the Registrar's own metadata triggers a GRID update. 2. The design allows a separation between registrar keys used for the GRID Git interactions and those used for actual DIA mathematical operations.

2.3 Internal design consequence - "Sidecar" Verification (Chain of Custody)​

Having decided to use a Git based model and a pull (harvest) mechanism, a technical detail to solve was that Git Signatures live in the .git folder, not the file itself. When moving files to the build stage, the signature is lost.

  • Solution: We verify at source (during a clone operation) and generate a .sig "sidecar" file.
  • Mechanism: companies.md is paired with companies.sig.
  • Result: The build script trusts the sidecar, maintaining the chain of custody across pipeline stages.

2.4 Strict Issuance Rules (No DID = No Anchor)​

The pipeline enforces strict business logic regarding the issuance of W3C Verifiable Credentials.

  • Decision: The GRID will only issue a Digital Identity Anchor if the harvested data possesses a valid cryptographic signature and the participant has provided a Decentralized Identifier (DID).
  • Outcome: Registries missing a DID will be logged in the public GRID directory with a warning (⚠️ No DID Provided), ensuring transparency while maintaining strict semantic schema requirements.

3. Technical Implementation​

3.1 The Harvester (.gitlab-ci.yml)​

The pipeline runs on a schedule to ingest external data.

  1. Inject Credentials: Uses git-credential-store to clone private sovereign repos.
  2. Import Key & Trust: Imports the Sovereign's Public GPG Key and applies signature checks against the pulled content.
  3. File naming and placing: Reads country_code from the harvested file frontmatter, creates a directory, and copies the verified file and its .sig sidecar.

3.2 The Generator (generate-grid.js)​

The script acts as the verification and publishing engine. It extracts the raw data and wraps it in a JSON-LD framework.

:::note Future Improvements This approach can/will be improved on. For example:

  1. Only pull data from registers with updates, and only update those files that have changed.
  2. The operational system needs a better mechanism to manage the list of Registrars to pull data from. :::

Key functions of the pilot generator:

  1. Strict Mode Verification: Checks the sidecar or local Git log. Any status other than G (Good) is marked as "Unverified" and rejected from credential issuance.
  2. UNTP Credential Issuance: Maps the harvested YAML data directly into the strict JSON-LD schema required by the UNTP Digital Identity Anchor specification.
  3. Multi-Format Outputs: Dynamically generates a human-readable Markdown directory (with relative UI links) and a machine-readable CSV directory containing absolute URLs (e.g., https://grid.unece.org/dias/at_tp-alr.json) for downstream Relying Parties.

3.3 Cryptographic Security Adapter (The Signing Engine)​

To issue valid W3C Verifiable Credentials, the GRID must sign the JSON payloads with its own private key.

  • Pilot Phase (Local Execution): The script uses an isolated, masked GitLab CI/CD environment variable (GRID_MASTER_PRIVATE_KEY) to natively generate standard W3C Ed25519Signature2020 Linked Data proofs. This key is explicitly designated for data signing and possesses no infrastructure privileges.
  • Production Phase (HSM Upgrade): The code is structured using an Adapter Pattern. In a fully operational environment, the local Node.js cryptographic signing function will be replaced with a secure API call to an external Hardware Security Module (HSM) or Cloud Key Management Service.

4. Operational Guide for Ops Team​

Adding a New Pilot Participant​

To onboard a new participant (e.g., Australia), the UNICC team:

  1. Receive Public Address and Keys: gets the Repo URL, Deploy Token, and Public Key (.asc) from the participant lead.
  2. Update Variables: Adds the credentials to the GitLab CI/CD Variables.
  3. Update Pipeline: Edits .gitlab-ci.yml to clone the new repo and import the key.
  4. Commit: The next pipeline run will automatically harvest, verify, sign, and display the Australian nodes.

5. Detailed Design​

This architecture enables a pilot of the UN/CEFACT GTR Project "Global Registry Information Directory" (GRID). It simulates a trust ecosystem using standard Git cryptography and CI/CD automation.

5.1 The Components​

  • The GRID Hub (UNICC): The central Docusaurus project. It hosts the website, issues the Verifiable Credentials, and runs the aggregation pipeline.
  • The Sovereign Nodes: Private or public projects owned by Pilot Registrars. They publish only their specific registrar data.
  • The Identity Layer: Participants sign their data commits with GPG/SSH keys, proving origin before the GRID Hub counter-signs the payload.

5.2 DIA Hosting (The /dias Folder)​

Instead of generating raw DID documents for participants, the GRID generates and hosts authoritative Digital Identity Anchors (W3C Verifiable Credentials).

Directory Structure (UNICC Repo):

/static/dias/
          ├── at_tp-alr.json   (Atlantis Land Registry DIA)
          ├── at_tp-acr.json   (Atlantis Companies Registry DIA)
          └── gv_tp-mgc.json   (Genovia Companies DIA)

The resolution URL for a verifier becomes: https://grid.unece.org/dias/at_tp-alr.json

5.3 Data Specification (Markdown + Frontmatter)​

This format bridges the gap between machine-readable data (YAML) and human-readable context (Markdown). The schema is validated by the validate-schema.js script prior to generating the GRID table or issuing a credential.

Example markdown:

---
UN_member_state: GV
registrar_full_name: "TP: Royal Ministry of Genovia Companies"
registrar_identifier_code: TP-MGC
register_type: "Organisation"

# Pointing to the Registrar's self-hosted DID
did: "did:web:gitlab.com:gtr-pilots:genovia"
status: "active"
---
## Royal Ministry of Genovia
This registry is a test pilot bootstrap node...

5.4 The Aggregation Logic (The Scripts)​

The GRID is generated dynamically by the generate-grid.js script.

The GRID Pilot organizes input data as follows:

/
├── static/dias/            # Hosted UNTP Verifiable Credentials
├── registrars/
│   ├── internal/           # Fictitious Markdown files
│   └── external/           # Real Pilot files
└── scripts/
    ├── generate-grid.js    # The Logic & Cryptographic Engine
    └── validate-schema.js  # The parsing engine

6. Future Improvements​

The pilot design is deliberately constrained, there are a number of future improvements that may be considered:

  • Enterprise Key Management: Migrating the local signDigitalIdentityAnchor adapter function to utilize an external Hardware Security Module (HSM).

  • Automated Membership Management: Transitioning from manual .yml updates to an Automated Onboarding Portal where Registrars submit their own Public Keys and metadata.

  • Cost-Recovery Simulation: Tracking the "Compute/Storage Credits" used by each node to model future membership fees.

  • Semantic Allow-listing: Transitioning the JSON-LD payload generator from a "map all" approach to a strict schema allow-list to ensure absolute compliance with downstream verifier software.