# CN86 号码资源注册数据库规范
_草案，版本 01_

## 关于本文
本文是一份 CN86 规范草案。

本文尚未经过 CN86 社区的审议，不应作为规范使用。

关于此份草案的意见和建议，欢迎在 CN86 QQ 群提出。

## 维护者注册数据库
维护者应当通过 CN86 Gitea 平台创建维护者注册数据库，以取得 CN86 号码资源分配，并通过该数据库进行后续管理和维护。

维护者注册数据库的名称必须为 `.cn86registry`，并可通过其 Gitea 平台账号的命名空间（即 `git.cn86.dev/<username>/.cn86registry`）访问。

该仓库可见性应当设置为公有。

### `resources.yaml`
维护者注册数据库（`.cn86registry`）必须包含文件 `resources.yaml` 文件。

`resources.yaml` 文件应当符合 YAML 语法。下面给出 `resources.yaml` 文件的示例：

**`resources.yaml` 文件示例**
```yaml
auth:
  - ssh-ed25519 AAA...
email:       nic@cn86.dev
description: CN86 Network Information Center
qq:          10001
twitter:     @elonmusk
bilibili:    36081646
activitypub:
  - nic@mastodon.cn86.dev
  - nic@misskey.cn86.dev
ipv4:
  - address:       10.86.86.0/24
    description:   CN86 Anycast Network
    nameservers:   [ns1.dns.cn86, ns2.dns.cn86]
    geofeed:       https://geofeed.anycast.cn86/geofeed.csv
    country:       CN
    subdivision:   SH
    iata:          SHA
    geolocation:   30.9176 121.9197
    postal:        201308
domains:
  - name:          anycast.cn86
    nameservers:   [ns1.dns.cn86, ns2.dns.cn86]
  - name:          dns.cn86
    nameservers:
      - server:    ns1.example.cn86
        addresses: 10.86.86.53
      - server:    ns2.example.cn86
        addresses:
          - 10.86.86.54
          - 10.86.86.55
```

#### `resources.yaml` 文件的字段
`resources.yaml` 文件的数据结构，参照下方给出的 TypeScript 定义：

```typescript
type ALPHA =
    'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G' | 'H' |
    'I' | 'J' | 'K' | 'L' | 'M' | 'N' | 'O' | 'P' |
    'Q' | 'R' | 'S' | 'T' | 'U' | 'V' | 'W' | 'X' |
    'Y' | 'Z';
type DIGIT =
    '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' |
    '8' | '9';
type ALPHADIGIT = ALPHA | DIGIT;

type IPv4Address = `${number}.${number}.${number}.${number}`;
type IPv6Address = string;
type CountryCode = `${ALPHA}${ALPHA}`;
type SubdivisionCode = `${ALPHADIGIT}${ALPHADIGIT}`;
type SSHPublicKey = `ssh-ed25519 ${string}` | `ssh-rsa ${string}` |
    `ssh-ecdsa-nistp256 ${string}` |
    `ssh-ecdsa-nistp384 ${string}` |
    `ssh-ecdsa-nistp521 ${string}`;
type NonEmptyArray<T> = [T, ...T[]];
type OneOrMore<T> = T | NonEmptyArray<T>;

/**
 * CN86 维护者注册数据库的 `resources.yaml` 文件数据结构
 */
type MaintainerRegistryEntry = Maintainer & MaintainerResources;
```

## 中心注册数据库
中心注册数据库的应当在 `cn86` 命名空间下，并命名为 `registry`。

中心注册数据库的应当可通过 `git.cn86.dev/cn86/registry` 命名空间访问。

中心注册数据库的应当使用下面的文件系统结构：
```
git.cn86.dev/cn86/registry/index.json
git.cn86.dev/cn86/registry/ipv4/<ipv4>.json
git.cn86.dev/cn86/registry/domains/<domain>.json
git.cn86.dev/cn86/registry/maintainers/<username>.json
```

### 中心注册数据库的对象定义
中心注册数据库的文件应当符合规范的 JSON 语法。其中对象的定义，参照以下 TypeScript 定义：

#### `index.json` 文件
```typescript
/**
 * CN86 中心注册数据库的 `index.json` 索引文件结构
 */
interface CentralRegistryIndex {
    type: "registry-index";
    maintainers: string[];
    ipv4: IPv4Address[];
    domains: `${string}.cn86`[];
    source: `CN86`;
}
```

#### `maintainers/<maintainer>.json` 文件
```typescript
/**
 * CN86 中心注册数据库的基础数据结构
 */
interface CentralRegistryEntry<T extends
    ("maintainer" | "ipv4" | "domain")
> {
    type: T;
    maintainer: Maintainer;
    source: `CN86`;
}

/**
 * CN86 中心注册数据库的 `cn86/registry/maintainers/<maintainer>.json` 文件数据结构
 */
type CentralRegistryMaintainerEntry = Record<string,
    Maintainer & CentralRegistryEntry<`maintainer`>>;

```

#### `ipv4/<ipv4>.json` 文件
```typescript
/**
 * CN86 中心注册数据库的 `cn86/registry/ipv4/<ipv4>.json` 文件数据结构
 */
type CentralRegistryIPv4Entry = Record<`${IPv4Address}_${number}`,
    IPv4Resource & CentralRegistryEntry<`ipv4`>>;
```

#### `domains/<domain>.json` 文件
```typescript
/**
 * CN86 中心注册数据库的 `cn86/registry/domains/<domain>.json` 文件数据结构
 */
type CentralRegistryDomainEntry = Record<`${string}.cn86`,
    DomainResource & CentralRegistryEntry<`domain`>>;
```

## 数据结构
前文提到的数据结构，参照下方给出的 TypeScript 定义。

### 基础架构
所有数据结构都可任意扩展，包括定义未在本文中说明或保留的字段。
```typescript
/**
 * CN86 数据结构的基础架构
 */
interface ExtraFields {
    /**
     * **[可选]**
     * 
     * 资源的其他属性，可自行定义。
     */
    [key: string]: any;
}
```

### 维护者及其所有资源
```typescript
/**
 * CN86 的资源维护者
 */
interface Maintainer extends ExtraFields {
    /**
     * **[必填][非空数组]**
     * 
     * 维护者 SSH 公钥，用于身份认证。
     * 
     * 可以是字符串，也可以是字符串数组。
     * 
     * 至少填写一个。
     */
    auth: OneOrMore<SSHPublicKey>;

    /**
     * **[可选]**
     * 
     * 维护者的描述，可以为任意形式文本。
     */
    description?: string;

    /**
     * **[必填][消费者应当 (SHALL) 实现]**
     * 
     * 维护者的电子邮件，用于联系和身份认证。
     */
    email: OneOrMore<`${string}@${string}`>;

    /**
     * **[可选][消费者可选 (OPTIONAL) 实现]**
     * 
     * 维护者的 QQ。
     * 
     * `number` 类型为 QQ 号。
     * 
     * `string` 类型为 QID。
     */
    qq?: OneOrMore<number | string>;

    /**
     * **[可选][消费者可选 (OPTIONAL) 实现]**
     * 
     * 维护者的微信号。
     * 
     * 可以填写手机号或微信号。
     */
    wechat?: OneOrMore<number | string | `wxid_${string}`>;

    /**
     * **[可选][消费者可选 (OPTIONAL) 实现]**
     * 
     * 维护者的 Telegram 账号，开头包含 `@`。
     * 
     * 可以填写手机号或微信号。
     */
    telegram?: OneOrMore<`@${string}`>;

    /**
     * **[可选][消费者可选 (OPTIONAL) 实现]**
     * 
     * 维护者的 Twitter (X) 账号，开头包含 `@`。
     */
    twitter?: OneOrMore<`@${string}`>;

    /**
     * **[可选][消费者可选 (OPTIONAL) 实现]**
     * 
     * 维护者的 BlueSky 账号，开头包含 `@`。
     */
    bluesky?: OneOrMore<`@${string}`>;

    /**
     * **[可选][消费者可选 (OPTIONAL) 实现]**
     * 
     * 维护者的 ActivityPub 协议的联邦宇宙 (FediVerse) 社交媒体账号。格式为 `@{user}@{server}`。
     */
    activitypub?: OneOrMore<`@${string}@${string}`>;

    /**
     * **[可选][消费者可选 (OPTIONAL) 实现]**
     * 
     * 维护者的微博账号。
     * 
     * `number` 类型为 URL 中的 UID。
     * 
     * `@${string}` 类型为 `@` 开头的用户名。
     */
    weibo?: OneOrMore<number | `@${string}`>;

    /**
     * **[可选][消费者可选 (OPTIONAL) 实现]**
     * 
     * 维护者的抖音账号。
     */
    douyin?: OneOrMore<string>;

    /**
     * **[可选][消费者可选 (OPTIONAL) 实现]**
     * 
     * 维护者的 TikTok 账号。
     */
    tiktok?: OneOrMore<string>;

    /**
     * **[可选][消费者可选 (OPTIONAL) 实现]**
     * 
     * 维护者的哔哩哔哩账号。需要填写 UID。
     * 
     * 注意 UID 的范围为 64 位无符号整数。
     */
    bilibili?: OneOrMore<number>;
}

/**
 * CN86 的资源维护者所拥有的资源
 */
interface MaintainerResources {
    /**
     * **[保留]**
     * 
     * 维护者拥有的自治系统号资源。
     * 
     * **保留以供未来使用，禁止自定义字段使用此名称。**
     */
    asn: null | undefined

    /**
     * **[保留]**
     * 
     * 维护者拥有的 E.164 (电话号码) 资源。
     * 
     * **保留以供未来使用，禁止自定义字段使用此名称。**
     */
    e164: null | undefined

    /**
     * **[必填][可为空数组]**
     * 
     * 维护者拥有的 IPv4 资源。
     */
    ipv4: IPv4Resource[];

    /**
     * **[保留]**
     * 
     * 维护者拥有的 IPv6 资源。
     * 
     * **保留以供未来使用，禁止自定义字段使用此名称。**
     */
    ipv6: null | undefined

    /**
     * **[必填][可为空数组]**
     * 
     * 维护者拥有的域名资源。
     */
    domains: DomainResource[];
}
```

### IP 地址
```typescript
/**
 * CN86 的 IPv4 资源
 */
interface IPv4Resource extends IPResource {
    /**
     * **[必填]**
     * 
     * IPv4 资源的 CIDR 表示。
     */
    address: `${IPv4Address}/${number}`;
}

/**
 * CN86 IP 地址资源条目的通用字段
 */
interface IPResource extends ExtraFields {
    /**
     * **[可选]**
     * 
     * IP 资源的描述，可以为任意形式文本。
     */
    description?: string;

    /**
     * **[可选][消费者应当 (SHELL) 实现]**
     * 
     * 如果填写空数组，视为未填写。
     * 
     * IP 的反向解析名称服务器。
     */
    nameservers?: string[];

    /**
     * **[必填][消费者必须 (MUST) 实现]**
     * 
     * IP 地址的所属国家，格式为 [ISO 3166-1 Alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)
     * 格式的国家代码。
     */
    country: `${ALPHA}${ALPHA}`;

    /**
     * **[选填][消费者应当 (SHELL) 实现]**
     * 
     * IP 地址的所属国家，格式为 [ISO 3166-2 Alpha-2](https://en.wikipedia.org/wiki/ISO_3166-2)
     * 格式的国家代码。
     */
    subdivision?: `${ALPHADIGIT}{ALPHADIGIT}`;

    /**
     * **[选填][消费者推荐 (RECOMMEND) 实现]**
     * 
     * IP 地址的 Geofeed，应当为指向一个 [RFC 8805](https://www.rfc-editor.org/rfc/rfc8805.html)
     * 格式 CSV 的 URL。
     */
    geofeed?: string;

    /**
     * **[可选][消费者推荐 (RECOMMEND) 实现]**
     * 
     * IP 地址的位置坐标，格式为 `[纬度] [经度]`。
     */
    geolocation?: `${number} ${number}`;

    /**
     * **[可选][消费者可选 (OPTIONAL) 实现]**
     * 
     * IP 地址的邮政编码。
     */
    postal?: `${number} ${number}`;

    /**
     * **[可选][消费者可选 (OPTIONAL) 实现]**
     * 
     * IP 地址所属或附近机场（或港口）的 IATA 或 FAA 编码。
     */
    iata?: `${ALPHADIGIT}${ALPHADIGIT}${ALPHADIGIT}`;

    /**
     * **[可选][消费者可选 (OPTIONAL) 实现]**
     * 
     * IP 地址的 [梅登黑德网格](https://en.wikipedia.org/wiki/Maidenhead_Locator_System)。
     */
    maidenhead?: `${number} ${number}`;
}
```

### 域名
```typescript
/**
 * CN86 的域名资源
 */
interface DomainResource extends ExtraFields {
    /**
     * **[必填]**
     * 
     * CN86 顶级（一级）域下的的二级域名资源名称。
     */
    domain: `${string}.cn86`;

    /**
     * **[可选]**
     * 
     * 域名资源描述，可以为任意形式文本。
     */
    description?: string;

    /**
     * **[必填][非空数组]**
     * 
     * 域名资源的权威解析服务器。
     * 
     * 应 (SHOULD) 填写 CN86 域名组成的数组，或 Glue 记录数据结构组成的数组。
     * 
     * 若有 Glue 记录，Glue 记录的地址也应指向 CN86 IP 地址。
     * 
     * 消费者可选 (OPTIONAL) 实现通过公网域名解析。
     * 
     * 至少填写一个。
     */
    nameservers: NonEmptyArray<string | {
        server: string;
        addresses?: OneOrMore<IPv4Address | IPv6Address>;
    }>;
}
```

## 聚合代理
### 聚合代理的行为
聚合代理应当在维护者注册数据库创建、更新和删除时，执行下文所述的聚合流程。

聚合代理也应当定期执行下文所述的聚合流程。

### 聚合代理的聚合流程
 1. 聚合代理通过 Gitea 平台提供的 API 列举所有维护者注册数据库 (`.cn86registry` 仓库)，并按本文所述规范，读取并解析仓库中的注册数据库文件。
 2. 聚合代理对相关文件进行 YAML 解析和字段格式验证。
     - 如果遇到错误，聚合代理应使用 Email、Gitea Issue 或其他方式通知用户。
     - 聚合代理应进行状态管理，对于关于同一注册数据库文件，只向同一用户通知一次。
     - 聚合代理应该能包容单个维护者或单个文件的错误，并继续处理其他维护者或同一维护者的其他文件。
 3. 聚合代理检查新增号码资源是否和已有号码资源冲突。
     - 如果遭遇错误，聚合代理应通过 Gitea Issue、电子邮件等方式，向试图新增该号码资源的用户发送通知。
     - 对于号码资源主键的修改，聚合代理应该视为删除已存在资源，和新增号码资源两个操作。
     - 聚合代理不应向已有号码资源的维护者发送通知。
     - 聚合代理应进行状态管理，对于关于同一冲突资源，向同一用户只通知一次。
     - 聚合代理应该能号码资源冲突，处理冲突后应能继续聚合流程。
 4. 聚合代理对号码资源的修改和删除进行身份验证。
     - 对于已存在的号码资源，聚合代理应当拒绝非其维护者发起的修改或删除操作。
     - 聚合代理应当基于 Gitea 平台的唯一 ID，而非用户名进行身份认证的判断。
     - 对于失败的身份验证，聚合代理应分别向已存在资源的维护者，和试图修改或删除资源的维护者，通过 Email、Gitea Issue 或其他方式通知用户。
 5. 聚合代理按照本文所述的文件系统和数据结构，应用中心注册数据库的更新。

## 术语表
本文中使用的「必须 (MUST)」、「不得 (MUST NOT)」、「必需 (REQUIRED)」、「应当 (SHALL)」、「不应当 (SHALL NOT)」、「应 (SHOULD)」、「不应 (SHOULD NOT)」、「建议 (RECOMMENDED)」、「不建议 (NOT RECOMMENDED)」、「可 (MAY)」、「可选 (OPTIONAL)」词汇，应按照 [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119) 中给出的定义解释。

本文定义了以下术语：
 - **号码资源**：用于网际互联和路由的标识符。在 CN86 中，特指由 CN86 分配和管理，用于 CN86 参与者网络间互联和路由的 IPv4 地址和 `.cn86` 域。
 - **Gitea 平台**：在 git.cn86.dev 上提供服务，以供 CN86 参与者管理和维护网络资源和其他元信息的 Gitea 应用。
 - **维护者**：在 CN86 Gitea 平台注册，以本文所述方式，对 CN86 网络号码资源进行管理和维护的 CN86 参与者。
 - **聚合代理**：通过访问维护者注册数据库，实现特定的完整性和一致性检查、权限控制、信息存取机制，以实现对 CN86 号码资源管理维护，并产生维护者注册数据库的数据处理程序。
 - **注册数据库**：通过 CN86 Gitea 平台上的数据存取，实现对 CN86 号码资源进行管理和维护的 Git 仓库。
 - **中心注册数据库**：由 CN86 所有，包含所有由 CN86 已分配的号码资源信息，并通过聚合代理以自动化方式管理的注册数据库。
 - **维护者注册数据库**：由维护者所有，仅包含维护者取得分配的号码资源信息，并由维护者自行管理的注册数据库。

本文中所定义的术语，在不引起歧义的情况下，均可省略「CN86」前缀。