@aigne/afs-dns 1.11.0-beta.6

package/LICENSE.md

@@ -0,0 +1,26 @@
+# Proprietary License
+
+Copyright (c) 2024-2025 ArcBlock, Inc. All Rights Reserved.
+
+This software and associated documentation files (the "Software") are proprietary
+and confidential. Unauthorized copying, modification, distribution, or use of
+this Software, via any medium, is strictly prohibited.
+
+The Software is provided for internal use only within ArcBlock, Inc. and its
+authorized affiliates.
+
+## No License Granted
+
+No license, express or implied, is granted to any party for any purpose.
+All rights are reserved by ArcBlock, Inc.
+
+## Public Artifact Distribution
+
+Portions of this Software may be released publicly under separate open-source
+licenses (such as MIT License) through designated public repositories. Such
+public releases are governed by their respective licenses and do not affect
+the proprietary nature of this repository.
+
+## Contact
+
+For licensing inquiries, contact: legal@arcblock.io

package/README.md

@@ -0,0 +1,233 @@
+# @aigne/afs-dns
+
+AFS DNS Provider - 统一的 DNS 管理接口，支持多种 DNS 服务商。
+
+## 支持的 Provider
+
+| Provider | 配置值 | 说明 |
+|----------|--------|------|
+| AWS Route53 | `route53` | 默认 Provider，完整支持 |
+| Google Cloud DNS | `clouddns` | Google Cloud 托管 DNS |
+
+## 安装
+
+```bash
+pnpm add @aigne/afs-dns
+
+# Route53 需要 AWS SDK（已包含）
+# Cloud DNS 需要额外安装：
+pnpm add @google-cloud/dns
+```
+
+## 配置示例
+
+### Route53 (AWS)
+
+```toml
+[[mounts]]
+path = "/dns/aws"
+uri = "dns://example.com"
+access_mode = "readwrite"
+
+[mounts.options]
+provider = "route53"
+region = "us-east-1"
+
+[mounts.options.credentials]
+accessKeyId = "${AWS_ACCESS_KEY_ID}"
+secretAccessKey = "${AWS_SECRET_ACCESS_KEY}"
+
+[mounts.options.permissions]
+preset = "standard"  # safe | standard | full
+```
+
+### Cloud DNS (Google Cloud)
+
+```toml
+[[mounts]]
+path = "/dns/gcp"
+uri = "dns://example.com"
+access_mode = "readwrite"
+
+[mounts.options]
+provider = "clouddns"
+projectId = "my-gcp-project"
+keyFilename = "/path/to/service-account.json"
+
+[mounts.options.permissions]
+preset = "standard"
+```
+
+### LocalStack (本地测试)
+
+```toml
+[[mounts]]
+path = "/dns/local"
+uri = "dns://test.local"
+access_mode = "readwrite"
+
+[mounts.options]
+provider = "route53"
+endpoint = "http://localhost:4566"
+region = "us-east-1"
+
+[mounts.options.credentials]
+accessKeyId = "test"
+secretAccessKey = "test"
+```
+
+## 使用方式
+
+### CLI
+
+```bash
+# 列出所有记录
+afs ls /dns/aws
+
+# 读取记录
+afs read /dns/aws/www
+
+# 读取 Zone 元数据
+afs read /dns/aws/_zone
+
+# 创建/更新记录
+afs write /dns/aws/api --content '{"type":"A","ttl":300,"values":["1.2.3.4"]}'
+
+# 删除记录
+afs rm /dns/aws/old-record
+
+# 删除特定类型
+afs rm /dns/aws/www?type=AAAA
+```
+
+### 编程式使用
+
+```typescript
+import { DNSProvider, Route53Adapter, CloudDNSAdapter } from "@aigne/afs-dns";
+
+// Route53
+const route53 = new Route53Adapter({
+  region: "us-east-1",
+  credentials: {
+    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+  },
+});
+
+// Cloud DNS
+const cloudDNS = new CloudDNSAdapter({
+  projectId: "my-project",
+  keyFilename: "/path/to/service-account.json",
+});
+
+// 创建 Provider
+const provider = new DNSProvider({
+  zone: "example.com",
+  adapter: route53, // 或 cloudDNS
+  accessMode: "readwrite",
+  permissions: { preset: "standard" },
+});
+
+// 列出记录
+const records = await provider.list("/");
+
+// 读取记录
+const www = await provider.read("/www");
+
+// 写入记录
+await provider.write("/api", {
+  content: { type: "A", ttl: 300, values: ["1.2.3.4"] },
+});
+```
+
+## 目录结构
+
+```
+/dns/example.com/
+├── @                    # 根域名记录 (apex)
+├── www                  # www.example.com
+├── api                  # api.example.com
+├── *.staging            # 通配符记录
+├── _dmarc               # DMARC 记录
+└── _zone                # Zone 元数据（只读）
+```
+
+## 支持的记录类型
+
+| 类型 | 值格式 | 示例 |
+|------|--------|------|
+| A | `string[]` | `["1.2.3.4", "5.6.7.8"]` |
+| AAAA | `string[]` | `["2001:db8::1"]` |
+| CNAME | `string` | `"alias.example.com"` |
+| MX | `{priority, value}[]` | `[{"priority": 10, "value": "mail.example.com"}]` |
+| TXT | `string[]` | `["v=spf1 include:..."]` |
+| NS | `string[]` | `["ns1.example.com"]` |
+| SRV | `{priority, weight, port, target}[]` | `[{"priority": 10, "weight": 5, "port": 443, "target": "..."}]` |
+| CAA | `{flags, tag, value}[]` | `[{"flags": 0, "tag": "issue", "value": "letsencrypt.org"}]` |
+| PTR | `string` | `"host.example.com"` |
+| SOA | (只读) | 区域授权记录 |
+
+## 权限模型
+
+危险操作默认禁止，需要显式配置开启：
+
+| 操作 | 默认 | 说明 |
+|------|------|------|
+| `read` | 允许 | 读取任何记录 |
+| `write` | 按 access_mode | 普通记录写入 |
+| `delete` | 按 access_mode | 普通记录删除 |
+| `modify_root` | 禁止 | 修改根域名 (@) |
+| `modify_ns` | 禁止 | 修改 NS 记录 |
+| `modify_wildcard` | 禁止 | 修改通配符 (*) |
+| `delete_zone` | 禁止 | 删除整个 Zone |
+
+### 预设模式
+
+```toml
+[mounts.options.permissions]
+preset = "standard"  # 选择预设
+```
+
+| 预设 | write | delete | modify_root | modify_ns |
+|------|-------|--------|-------------|-----------|
+| `safe` | ✓ | ✗ | ✗ | ✗ |
+| `standard` | ✓ | ✓ | ✗ | ✗ |
+| `full` | ✓ | ✓ | ✓ | ✓ |
+
+### 显式开启危险操作
+
+```toml
+[mounts.options.permissions]
+preset = "standard"
+
+[mounts.options.permissions.dangerous]
+modify_root = true      # 允许修改根域名
+modify_wildcard = true  # 允许修改通配符
+```
+
+## E2E 测试
+
+使用 LocalStack 进行本地测试：
+
+```bash
+# 启动 LocalStack
+docker run -d --name localstack-dns \
+  -p 4566:4566 \
+  -e SERVICES=route53 \
+  localstack/localstack
+
+# 运行测试
+cd providers/dns
+pnpm test:e2e:full
+```
+
+## 依赖
+
+- `@aws-sdk/client-route-53` - AWS Route53 SDK（内置）
+- `@google-cloud/dns` - Google Cloud DNS SDK（可选，peer dependency）
+
+## 注意事项
+
+- Route53 API 有请求限制（5 requests/second），内置 rate limiting
+- DNS 变更是最终一致的，写入后可能需要等待传播
+- Zone 创建/删除不在 AFS 范围内（通过云控制台或 IaC 工具管理）