kivaprotocol/aries-key-guardian

aries-key-guardian

镜像概述和主要用途

aries-key-guardian 是一个可互操作的密钥保护和恢复系统，专为自主主权身份（SSI）设计，提供密钥托管、验证及恢复功能，支持身份的安全管理与访问控制。

核心功能和特性

• 密钥托管与验证：通过 /v1/escrow/verify 路由验证***访问权限
• 即时***（Just-in-Time Wallets）：当验证时发现不存在，可自动创建新
• 数据库迁移支持：基于 TypeORM 实现数据库结构变更与版本控制
• 灵活配置：通过环境变量自定义系统行为，支持集成外部控制器

使用场景和适用范围

适用于需要安全管理自主主权身份***密钥的场景，如：

• SSI ***服务提供商
• 身份验证系统集成
• 多用户身份管理平台
• 需要密钥恢复机制的分布式身份应用

使用方法和配置说明

环境准备

1. 复制 dummy.env 内容到项目根目录的 .env 文件，可手动复制或运行脚本：

   bash
   ./scripts/useDummyEnv.sh
   

2. 从 aries-guardianship-agency 仓库启动代理网络：

   bash
   npm install
   docker-compose up
   

即时***（Just-in-Time Wallets）配置

"即时***"指当指定 ID 的不存在时自动创建的功能。除通过 /v1/escrow/create 路由手动创建外，可配置为访问 /v1/escrow/verify 路由时自动触发创建。

需设置以下环境变量启用该功能：

1. JIT_WALLETS_ENABLED=true：启用即时***流程
2. INTEGRATION_CONTROLLER：指定负责协调监护系统访问的控制器地址，该控制器需提供 /v1/api/onboard 路由（接收基础 ID 并返回创建的代理 ID），例如："http://kiva-controller:8081"

可通过本地 .env 文件、Kubernetes 密钥或其他部署方式设置这些环境变量。

测试方法

可通过以下两种方式运行测试：

1. 在 Docker 容器内运行：

   bash
   docker exec -it aries-key-guardian npm run test
   

2. 在本地（Mac）运行：

   bash
   npm run test
   

数据库迁移

有关 TypeORM 迁移的详细信息，请参考 https://github.com/typeorm/typeorm/blob/master/docs/migrations.md%E3%80%82

创建新迁移

在项目根目录运行以下命令创建新的数据库迁移：

bash
npm run typeorm:migration NameOfNewMigration

该命令会在 src/migration 文件夹中生成一个包含时间戳和名称的 TypeScript 类（例如 src/migration/1610566582191-CreateTables.ts，类名为 CreateTables1610566582191）。时间戳决定迁移执行顺序，建议使用此命令生成迁移而非手动创建。

迁移类包含两个空函数：

• up(queryRunner: QueryRunner)：执行迁移时运行的代码
• down(queryRunner: QueryRunner)：回滚迁移时运行的代码

风格建议：优先使用 SQL 语句通过 queryRunner.query(...) 实现迁移，而非 TypeORM 的查询运行器 API，以确保数据库操作的可控性和确定性。

迁移开发流程

为避免频繁构建 Docker 镜像测试迁移，建议本地运行服务测试迁移：

1. 编辑 /etc/hosts 添加以下行：

   127.0.0.1       escrow-db
   ::1             escrow-db
   

2. 在 docker-compose.yml 中，注释 # ----------LOCAL MODE---------- 上方内容，取消下方内容注释

3. 启动本地 Docker 服务：

   bash
   docker-compose -f docker-compose.yml up --force-recreate
   

4. 编写/编辑迁移文件

5. 构建迁移：

   bash
   npm run build
   

6. 测试迁移：

   bash
   npm run start:debug
   

若出现错误或迁移未达预期，返回步骤 4 重复调整。