NAAN Registry - HackMD

# 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.

Syntax	Example	Reference
# Header	Header	基本排版
- Unordered List	Unordered List
1. Ordered List	Ordered List
- [ ] Todo List	Todo List
> Blockquote	Blockquote
Bold font	Bold font
Italics font	Italics font
~~Strikethrough~~	~~Strikethrough~~
19^th^	19^th
H~2~O	H₂O
++Inserted text++	Inserted text
==Marked text==	Marked text
[link text](https:// "title")	Link
![image alt](https:// "title")	Image
`Code`	`Code`	在筆記中貼入程式碼
```javascript var i = 0; ```	`var i = 0;`
:smile:		Emoji list
{%youtube youtube_id %}	Externals
$L^aT_eX$	L^aT_eX
:::info This is a alert area. :::	This is a alert area.