owned this note
owned this note
Published
Linked with GitHub
# NAAN Registry
The NAAN registry provides the source of truth for Name Assigning Authority Number (NAANs) records. These records associate a NAAN with a service for resolving ARK identifiers created under that NAAN prefix.
The NAAN registry provides two important roles:
1. Ensuring that NAANs are unique
2. Associating each NAAN with an ARK resolver service
Additionally, the metadata associated with each NAAN record can assist with monitoring and maintenance activities, as well as providing general information about the domain of a NAAN.
See also:
- [Resolver systems](https://hackmd.io/dor0GlmTSEuLYouGJ6TIjA)
- [ARKS org GitHub](https://github.com/arks-org)
- [Private NAANs](https://github.com/CDLUC3/naan_reg_priv)
- [Public NAANs](https://github.com/CDLUC3/naan_reg_public)
## Current situation
The NAAN registry currently (early 2024) consists of a source document (`main_naans`) in [ANVL format](https://datatracker.ietf.org/doc/html/draft-kunze-anvl-02) listing the registered NAANs, and a set of scripts for performing various checks and operations to assist with updating the source documents and disseminating changes. The registry is maintained as a [private git repository hosted by GitHub](https://github.com/CDLUC3/naan_reg_priv). The repository is private to protect personal information that may be contained in NAAN records (personal contact information).
The current workflow for creating and updating NAAN records uses a workflow involving several systems, and while functional, is difficult to maintain and can be cumbersome for NAAN registry maintainers.
## Upcoming Changes
The NAAN registry operational procedures are changing with a general focus on streamlining operations, increasing transparency, and simplifying maintenance.
An important change is a transition from ANVl to JSON for storing NAAN records. There are many technical benefits to this format which outweigh the reduction in human friendliness.
The storage and processing capabilities of GitHub will be leveraged for storing NAAN records and performing basic operations. This does increase dependency on GitHub, though the core elements for NAAN record storage and processing are implemented in an independent manner so that operations could be transitioned to another environment if necessary without significant disruption or loss of history.
A high level architecture view of the new NAAN infrastructure is depicted in Figure 1.
```plantuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
title NAANs,ARKs
Container(NS, "NAAN Schema", "NAAN Record formal definition")
Container(NE, "NAAN Editor", "Web UI for NAAN create and update")
Container(NR, "NAAN Records", "Repository of NAAN records")
Container(NPR, "Public NAAN Records", "Repository of public NAAN records")
Rel(NS, NE, "Informs")
Rel(NS, NR, "Defines")
Rel(NS, NPR, "Defines")
Rel(NE, NR, "Create, Update\n[Using GH Issue]")
Rel(NR, NPR, "Export\n[Using GH Action]")
Container(AO,"arks.org", "ARK NAAN resolver")
Rel(NPR, AO, "Configure\n[webhook]")
Container_Ext(N2T, "n2t.net", "N2T Scheme Resolver")
Rel(N2T, AO, "Redirect")
Rel(NE, AO, "Hosted by")
Container_Ext(IAR, "ARK Services", "Community ark resolver and resource servers")
Rel(AO, IAR, "Redirect")
```
**Figure 1.** Container diagram of the NAAN record infrastructure. NAAN record structure is defined by a JSON schema which is used to generate the editor and validate records in the private and public registries. New and updated NAAN records are submitted as GitHub issues to the private NAAN repository for attention by curators. Processing of NAAN records is performed by GitHub actions within the private NAAN repository. The public NAAN repository is updated in response to changes in the private NAAN repository. Instances of the arks.org resolver are updated with new configuration details when changes are made to the public NAAN repository.
### JSON representation of NAAN records
The NAAN registry shall be composed of a folder containing JSON documents, each document being a complete NAAN registration conforming with a JSON Schema defining the required properties of the records.
As there are more than a thousand authoritative NAAN records, the records shall be held in sub-folders named with the first character (1-9) of the NAAN records contained therein.
```
naans
├── 1
│ ├── 12345.json
│ └── ...
├── 2/
│ ├── 23456.json
│ └── ...
...
└── 9/
├── 99999.json
└── ...
```
Hence the full path to an authoritative NAAN record shall be:
```
naans/1/12345.json
```
Where `12345` is the NAAN value, and `1` corresponds to the first character of the NAAN value.
All path and file names shall be lower case and constrained to ASCII a-z, 1-9. This is necessary to avoid potential conflicts with file systems that are not case sensitive.
The JSON NAAN records will be generated from the `main_naans` ANVL source during initial phases of the registry transition (Figure 2). Technically, an update to `main_naans` will trigger a GitHub action that runs a python script to parse `main_naans`, update affected NAAN JSON records, and commit those changes.
```plantuml
actor Admin
participant Private
participant Action
participant Public
participant Action2
Admin -> Repo: update
Repo -> Action: notify main_naans updated
Action --> Action2: main_naans updated
Action2 -> Repo: pull
Action2 -> Action2: generate public JSON
Action2 -> Public: commit, push
```
**Figure 2.** Workflow for updating the public NAAN records while `main_naans` is source of truth.
This is currently implemented with https://github.com/CDLUC3/naan_reg_public
The workflow when `main_naans` is no longer the authoritative source will be similar, with the source of truth being the private NAAN records and the trigger being any update to those records.
### Maintenance of NAAN records
Three basic use cases need to be supported:
1. Create new NAAN records
2. Update existing NAAN records
3. Disseminate NAAN records to dependent services
#### Use Case: Create NAAN record
```plantuml
actor User
participant UI
participant Auth
participant Repo
actor Admin
User -> UI: New entry form
UI -> User: Email one-time-passcode
note right: Email addresses must be validated\nbefore the form can be submitted.
User -> UI: Verify OTP
UI -> UI: Validate Record
UI -> Repo: Create Issue
note right: Issue contains NAAN entry in JSON\nfor review and processing
UI --> User: OK
Repo -> Admin: Notify
Admin -> Admin: Review
Admin -> Repo: Approve
Repo -> Repo: GH Action
note right: Action assigns new NAAN, updates registry\nDownstream dependencies are informed.
Repo -> User: Notify
```
**Figure 3.** Sequence for creating a new NAAN record. Details are entered into a web form that is based on the NAAN JSON schema. Email addresses entered must be verified before the form can be submitted. A non-interactive recaptcha is used to help reduce spam requests. The record is submitted to GitHub as a new issue, and the NAAN record embedded in the issue as a block of JSON. After approval by a curator, the issue is submitted to a workflow that updates the registry and notifies downstream consumers.
#### Use Case: Update NAAN record
```plantuml
actor User
participant UI
participant Auth
participant Repo
actor Admin
User -> UI: NAAN and email
UI -> User: Email OTP
User -> UI: Verify OTP
UI -> User: Present NAAN record
User -> UI: edit record, submit
UI -> Repo: Create Issue
UI --> User: OK
Repo -> Admin: Notify
Admin -> Repo: Approve
Repo -> Repo: GH Action
Repo -> User: Notify
```
**Figure 4.** Update an existing NAAN record. The user specifies the NAAN and email address. A OTP is sent to the user via email, and when entered to the form, the full NAAN record is retrieved from the repository. On submission, a new issue is created in the GitHub repository, and processing continues as above with NAAN records updated and downstream consumers informed.
## Use Case: Distribute NAAN records
Public content is extracted and serialized to JSON as:
- a single json file
- a folder of individual json records
These are readily consumed by downstream applications and provide authoritative information for resolver services.
```plantuml
participant Repo
participant Workflow
participant Public as "Public Repo"
participant Universe as Public
Repo -> Repo: merge
Repo -> Workflow: Generate artifacts
Workflow -> Repo: Push release
Workflow -> Public: Notify
Public -> Repo: pull latest
Repo --> Public: latest
Public -> Universe: Notify
note right: There may be multiple subscribers\nfor release notification.
```
**Figure 5.** Sequence for distributing public NAAN records. After the private NAAN repository is updated, and action is triggered on the public repository. A public view of the NAAN records is generated and registered webhooks triggered.
Two repositories are invovled: the Private Repository and a Public Repository. The Private Repository is the source of truth and is not accessible without group membership. The Public Repository is updated only by workflows triggered by updates on the Private Repository. It contains only public portions of the NAAN records and broadcasts a notification to subscribers when an update is available.