Arnakoff

Arnakoff API

反诈骗公共 API：输入网站、电子邮件、电话号码、IBAN 或 SIREN，它会返回用法语说明并注明来源的信号。

状态

正在开发中：尚未发布任何版本，API 也尚未投入使用。cmd/ 中的命令目前都不起作用。请在路线图中查看进展。

API 的功能

你提供一个输入；API 会将其与公共来源（AMF 和 ACPR 黑名单、SIRENE 目录、BODACC、域名年龄、ARCEP 编号等）进行比对，并返回一系列信号。每个信号包含：

• code：信号的稳定标识符；
• level：信号级别；
• message：法语事实描述，例如“自 08/10/2026 起列入 AMF 黑名单”；
• source 和 source_url：数据发布方及其核验地址；
• observed_at：采集数据的日期。

计划提供的信号见 docs/signals.md，来源及其许可证见 docs/sources.md。API 还以 MCP 服务的形式提供：可通过 POST /mcp 远程访问，使用与 /v1/check 相同的密钥和配额；也可通过 cmd/mcp 在本地使用（stdio）。它以 com.arnakoff/api 为名称列入 MCP 官方注册表。

原则

• 绝不标记为“安全”。 如果没有信号，响应为“我们的来源中没有已知信号”：未列入黑名单并不能证明什么。
• 只陈述事实，不作指控。 每个信号都注明来源；任何消息都不会将具名实体称为诈骗。
• 优先考虑许可证。 只有在许可证允许商业再利用时才会使用该来源。
• 保护个人数据。 电子邮件、电话号码和 IBAN 绝不会以明文形式记录日志，也不会传给第三方。
• 绝不访问用户提供的 URL。 通过标识符查询登记信息，且仅访问允许列表中的主机。
• 谨慎同步。 无效的来源快照，或条目数量减少超过 20% 的快照，都会被拒绝；先前的快照会继续使用。

开始使用

你需要 Go 1.27：确切版本（toolchain go1.27.3）在 go.mod 中，并会自动下载。还需安装 docs/standards.md 中指定版本的 golangci-lint。

go build ./...
go vet ./...
golangci-lint run
go test -race -shuffle=on ./...
go tool govulncheck ./... tool

CI 会在每个拉取请求上运行相同的命令。测试绝不会使用网络。

使用 Docker 时，镜像（Dockerfile）基于不含 shell 的 distroless 镜像，并以非 root 用户运行 api、sync 和 admin 命令。compose.yaml 会启动 API 和同步服务，两者共用快照卷：

cp .env.example .env   # renseigner ARNAKOFF_LOG_KEY, ARNAKOFF_DATABASE_URL et ARNAKOFF_API_KEY_SECRET
docker compose up --build

每个已发布版本（标签 vX.Y.Z）都会为 linux/amd64 和 linux/arm64 构建镜像 ghcr.io/arnakoff/api，并标记为 X.Y.Z、X.Y 和 latest，同时生成 SBOM 和来源证明。镜像由 image.yml 工作流使用 cosign 无密钥签名；要验证某个版本的签名（此处为 0.48.0）：

cosign verify ghcr.io/arnakoff/api:0.48.0 \
  --certificate-identity https://github.com/arnakoff/api/.github/workflows/image.yml@refs/tags/v0.48.0 \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

可使用 docker buildx imagetools inspect ghcr.io/arnakoff/api:0.48.0 --format '{{ json .SBOM.SPDX }}'（或 '{{ json .Provenance.SLSA }}'）读取 SBOM 和来源证明。

组织结构

整洁架构（ADR 0002）：依赖关系只能向内。

目录	职责
internal/domain/	业务对象、输入规范化和信号规则，不涉及输入输出。
internal/app/	用例（验证、同步）及其所需的接口。
internal/adapter/	数据源、注册表、存储、HTTP API 和 MCP 服务。
internal/platform/	出站 HTTP 客户端、日志、配置。
cmd/	入口：api、sync、mcp 和 eval。

文档

• 架构决策：0001 — 技术基础、0002 — 整洁架构、0003 — 许可证、0004 — 密钥和配额存储、0005 — 生产环境托管、0006 — 保留期限。
• 标准和版本、数据源、信号。
• 网站和 API 公共文档位于 arnakoff/web。

参与贡献

请阅读 CONTRIBUTING.md。如发现安全漏洞，请遵循安全政策，切勿在公开 issue 中报告。如需帮助，请参阅 SUPPORT.md。

许可证

代码采用 GNU AGPL-3.0-only 许可证（ADR 0003）。数据沿用其来源所规定的许可证，详见 docs/sources.md。