alien-agent-id

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Alien Agent ID — Identity, Authentication & Credentials for AI Agents

Alien Agent ID — AI Agent的身份、认证与凭证管理

You are an AI agent. This skill gives you:

A cryptographic identity linked to a verified human owner (Alien Network)
Service authentication — signed tokens accepted by Alien-aware services
A credential vault — encrypted storage for API keys, passwords, OAuth tokens
Signed git commits — every commit traceable to you and your human owner

你是一个AI Agent。这个skill为你提供：

密码学身份标识 关联已验证的人类所有者（Alien Network）
服务身份验证 — 支持Alien的服务可识别的签名令牌
凭证保管库 — 加密存储API密钥、密码、OAuth令牌
git提交签名 — 每一次提交都可溯源到你和你的人类所有者

Quick Start

快速开始

Setting up an Alien Agent ID requires four steps run manually (not via

bootstrap

) so the QR code is visible to the user before the blocking poll begins.

Why not
bootstrap
? The
bootstrap
command combines all steps into one blocking call. Since tool output isn't streamed, the QR code would only appear after the command finishes — but it can't finish until the user scans the QR code. Running steps manually avoids this deadlock.

设置Alien Agent ID需要手动执行四个步骤（不要通过

bootstrap

命令），这样在阻塞轮询开始前，用户可以看到二维码。

为什么不用
bootstrap
？
bootstrap
命令会将所有步骤合并为一个阻塞调用。由于工具输出不会流式传输，二维码只会在命令执行完成后才会显示，但命令需要用户扫描二维码才能执行完成。手动执行步骤可以避免这种死锁。

Prerequisites

前置要求

Node.js 18+ and git 2.34+ available in the shell
Provider address: See below for how to resolve this.
Alien App: The user must have it installed with a verified AlienID

Node.js 18+ 和 git 2.34+ 已在shell环境中可用
服务商地址：请参考下文获取该地址
Alien App：用户必须已安装该应用并完成AlienID验证

Resolve the CLI path first

先解析CLI路径

The CLI tool is at

cli.mjs

in the same directory as this skill file. Before running any commands, resolve the absolute path. In all commands below, replace

CLI

with the resolved path:

node /absolute/path/to/cli.mjs

CLI工具位于本skill文件同级目录下的

cli.mjs

。执行任何命令前，请先解析其绝对路径。在下文中的所有命令里，请将

CLI

替换为解析后的路径：

node /absolute/path/to/cli.mjs

。

1) When to use

1) 适用场景

Check for an existing Alien Agent ID at the start of every session if you expect to make commits, call authenticated services, or access stored credentials.

bash

node CLI status

"bound": true

— you already have an Alien Agent ID. Skip to Section 6.

如果你需要进行提交、调用需要身份验证的服务，或者访问存储的凭证，请在每次会话开始时检查是否已存在Alien Agent ID。

bash

node CLI status

如果返回

"bound": true

— 你已经拥有Alien Agent ID，直接跳转到第6节。

Step 2: Choose provider and start authentication

第2步：选择提供商并开始认证

IMPORTANT: You MUST ask the user before proceeding. Never silently read
default-provider.txt
and use it without asking. The user must explicitly choose their provider.

Ask the user: "Would you like to use the default Alien provider (recommended), or set up your own?"

Default provider: Only after the user confirms, read the file
```
default-provider.txt
```
in the same directory as this skill file (next to
```
cli.mjs
```
) to get the address. Proceed to the
```
auth
```
command below.

Set up your own: Show the user this QR code and link to create a SSO provider. Wait for them to provide the address before proceeding.

Scan or open to set up your provider: https://dev.alien.org/dashboard/sso

▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
█ ▄▄▄▄▄ █▄▄████▀ ▄▀ ▄▄█ ▄▄▄▄▄ █
█ █   █ █ ▀█ ▄▄▄▄█▀█▀▄█ █   █ █
█ █▄▄▄█ █▄ ▄▄▀▄▀██▄█  █ █▄▄▄█ █
█▄▄▄▄▄▄▄█▄▀▄▀▄▀ ▀ ▀ ▀▄█▄▄▄▄▄▄▄█
█▄▄  ▀▀▄▀▄▀███▄▄▄ ▄▄ ▀ ▀▀ ▄▄█ █
█ ▄▀▄█▀▄ ▀██▀▀▀ ▀ █▀█▄▀▀  █▄▄▀█
██▀▄██ ▄█ ▄▀ █▀█  ▄█▀▄█▀▀█▄ ▀▀█
██▀▀▄▀█▄▀▄ ▄█ ▀▄███▀   █▀ █▄ ▄█
██  ▄ ▀▄█▄ █▄▀▀█▀▄█▄▄ ▄█▀▄ ▀ ██
█▄█▀▀ ▄▄▄█▄ ▄ ██   ▄▀█ ▄▄▄█ ███
██▄▄▄██▄▄  █▄  ▀▄▄  █ ▄▄▄   ▀▀█
█ ▄▄▄▄▄ ██  ▄▄▄████   █▄█  █ ██
█ █   █ █▀  ▀ █  ▀ ██▄ ▄  ▀▄▄▀█
█ █▄▄▄█ █ █▄ █▄▀█▄███ ██▄▀▀▄▀▄█
█▄▄▄▄▄▄▄█▄███▄█▄█▄█▄▄▄▄█████▄██

Then run:

bash

node CLI auth-header

This returns JSON with a

token

field. Use it in HTTP requests:

bash

undefined

重要提示：继续操作前你必须先询问用户。严禁在未告知用户的情况下静默读取
default-provider.txt
并使用其内容，用户必须明确选择自己的提供商。

询问用户："你希望使用默认的Alien提供商（推荐），还是自行设置？"

默认提供商：仅在用户确认后，读取本skill文件同级目录（
```
cli.mjs
```
旁边）的
```
default-provider.txt
```
文件获取地址，然后执行下方的
```
auth
```
命令。

自行设置：向用户展示下方的二维码和链接以创建SSO提供商，等待用户提供地址后再继续操作。

扫描或打开链接设置你的提供商：https://dev.alien.org/dashboard/sso

▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
█ ▄▄▄▄▄ █▄▄████▀ ▄▀ ▄▄█ ▄▄▄▄▄ █
█ █   █ █ ▀█ ▄▄▄▄█▀█▀▄█ █   █ █
█ █▄▄▄█ █▄ ▄▄▀▄▀██▄█  █ █▄▄▄█ █
█▄▄▄▄▄▄▄█▄▀▄▀▄▀ ▀ ▀ ▀▄█▄▄▄▄▄▄▄█
█▄▄  ▀▀▄▀▄▀███▄▄▄ ▄▄ ▀ ▀▀ ▄▄█ █
█ ▄▀▄█▀▄ ▀██▀▀▀ ▀ █▀█▄▀▀  █▄▄▀█
██▀▄██ ▄█ ▄▀ █▀█  ▄█▀▄█▀▀█▄ ▀▀█
██▀▀▄▀█▄▀▄ ▄█ ▀▄███▀   █▀ █▄ ▄█
██  ▄ ▀▄█▄ █▄▀▀█▀▄█▄▄ ▄█▀▄ ▀ ██
█▄█▀▀ ▄▄▄█▄ ▄ ██   ▄▀█ ▄▄▄█ ███
██▄▄▄██▄▄  █▄  ▀▄▄  █ ▄▄▄   ▀▀█
█ ▄▄▄▄▄ ██  ▄▄▄████   █▄█  █ ██
█ █   █ █▀  ▀ █  ▀ ██▄ ▄  ▀▄▄▀█
█ █▄▄▄█ █ █▄ █▄▀█▄███ ██▄▀▀▄▀▄█
█▄▄▄▄▄▄▄█▄███▄█▄█▄█▄▄▄▄█████▄██

然后执行：

bash

node CLI auth-header

这会返回包含

token

字段的JSON，可在HTTP请求中使用：

bash

undefined

Get the auth header for curl

获取curl用的auth header

AUTH=$(node CLI auth-header --raw) curl -H "$AUTH" https://service.example.com/api/whoami


The token is a self-contained Ed25519-signed assertion containing your fingerprint, public key, owner identity, and a timestamp. Tokens are valid for 5 minutes.

AUTH=$(node CLI auth-header --raw) curl -H "$AUTH" https://service.example.com/api/whoami


该令牌是经过Ed25519签名的自包含断言，包含你的指纹、公钥、所有者身份和时间戳，有效期为5分钟。

External services (vault credentials)

外部服务（保管库凭证）

For services that use API keys, passwords, or OAuth tokens, retrieve stored credentials from the vault:

bash

undefined

对于使用API密钥、密码或OAuth令牌的服务，可以从保管库中调取已存储的凭证：

bash

undefined

Retrieve a stored credential

调取已存储的凭证

node CLI vault-get --service github


Returns:
```json
{"ok": true, "service": "github", "type": "api-key", "credential": "ghp_xxx..."}

Use the

credential

value in the appropriate header or config for that service. For example:

bash

undefined

node CLI vault-get --service github


返回：
```json
{"ok": true, "service": "github", "type": "api-key", "credential": "ghp_xxx..."}

在对应服务的请求头或配置中使用

credential

的值，例如：

bash

undefined

GitHub API

GITHUB_TOKEN=$(node CLI vault-get --service github | node -e "process.stdin.resume(); let d=''; process.stdin.on('data',c=>d+=c); process.stdin.on('end',()=>console.log(JSON.parse(d).credential))") curl -H "Authorization: Bearer $GITHUB_TOKEN" https://api.github.com/user

Or more simply using jq if available

如果安装了jq可以使用更简单的写法

GITHUB_TOKEN=$(node CLI vault-get --service github | jq -r .credential)


If the credential doesn't exist in the vault, **ask the user** to provide it (see Section 3 below for the secure flow), then store it and retrieve again.

**Never hardcode credentials. Always use the vault.**

GITHUB_TOKEN=$(node CLI vault-get --service github | jq -r .credential)


如果保管库中不存在该凭证，请**询问用户**提供（安全流程请参考下文第3节），存储后再重新调取。

**严禁硬编码凭证，始终使用保管库存储。**

3) Credential vault

3) 凭证保管库

The vault encrypts credentials with a key derived from your agent's Ed25519 private key (HKDF + AES-256-GCM). Only this agent instance can decrypt them.

保管库使用从Agent的Ed25519私钥派生的密钥加密凭证（HKDF + AES-256-GCM），只有当前Agent实例可以解密这些凭证。

Storing credentials — the human-agent flow

存储凭证 —— 人类-Agent交互流程

When you need a credential for an external service, follow this protocol:

Step 1: Check if it's already stored

bash

node CLI vault-get --service github

If it returns the credential, use it. If not, continue.

Step 2: Ask the user

Tell the user exactly what you need and give them secure options to provide it:

"I need a GitHub personal access token to proceed. Please provide it using one of these methods (most secure first):

Option A — Write it to a temporary file:
echo 'ghp_your_token' > /tmp/gh-token && chmod 600 /tmp/gh-token
Then tell me the file path.

Option B — Set it as an environment variable and restart:
export GITHUB_TOKEN=ghp_your_token
Then tell me the variable name.

Option C — Paste it here and I'll store it immediately."

Step 3: Store it securely

Depending on which option the user chose:

bash

undefined

当你需要外部服务的凭证时，请遵循以下协议：

步骤1：检查是否已存储

bash

node CLI vault-get --service github

如果返回了凭证，直接使用即可，否则继续下一步。

步骤2：询问用户

明确告知用户你需要的内容，并提供安全的提供方式选项：

"我需要一个GitHub个人访问令牌才能继续操作，请通过以下任一方式提供（安全性从高到低排序）：

选项A — 写入临时文件：
echo 'ghp_your_token' > /tmp/gh-token && chmod 600 /tmp/gh-token
完成后告知我文件路径。

选项B — 设置为环境变量后重启：
export GITHUB_TOKEN=ghp_your_token
完成后告知我变量名。

选项C — 直接粘贴到此处，我会立即存储。"

步骤3：安全存储

根据用户选择的选项执行对应命令：

bash

undefined

Option A: from file (most secure — secret never on command line)

选项A：从文件读取（最安全 —— 密钥不会出现在命令行中）

node CLI vault-store --service github --type api-key --credential-file /tmp/gh-token

Then clean up the temp file:

随后清理临时文件：

rm /tmp/gh-token

Option B: from environment variable

选项B：从环境变量读取

node CLI vault-store --service github --type api-key --credential-env GITHUB_TOKEN

Option C: piped via stdin (secret not in process list)

选项C：通过stdin管道传入（不会出现在进程列表中）

echo 'ghp_xxx' | node CLI vault-store --service github --type api-key

Last resort: direct argument (visible in process list)

最后方案：直接作为参数传入（会在进程列表中可见）

node CLI vault-store --service github --type api-key --credential "ghp_xxx"


**Step 4: Confirm and use**
```bash
node CLI vault-get --service github

Use

--type

to tag what kind of credential it is:

```
api-key
```
— API key / personal access token (default)
```
password
```
— username + password pair (use with
```
--username
```
)
```
oauth
```
— OAuth access/refresh token
```
bearer
```
— Bearer token
```
custom
```
— Anything else

node CLI vault-store --service github --type api-key --credential "ghp_xxx"


**步骤4：确认并使用**
```bash
node CLI vault-get --service github

使用

--type

参数标记凭证类型：

```
api-key
```
— API密钥/个人访问令牌（默认）
```
password
```
— 用户名+密码对（配合
```
--username
```
使用）
```
oauth
```
— OAuth访问/刷新令牌
```
bearer
```
— Bearer令牌
```
custom
```
— 其他类型

Store examples

存储示例

bash

undefined

bash

undefined

GitHub personal access token (from file)

GitHub个人访问令牌（从文件读取）

echo 'ghp_abc123' > /tmp/cred && chmod 600 /tmp/cred node CLI vault-store --service github --type api-key --credential-file /tmp/cred rm /tmp/cred

AWS credentials (from env)

AWS凭证（从环境变量读取）

node CLI vault-store --service aws --type api-key --credential-env AWS_SECRET_ACCESS_KEY --username "$AWS_ACCESS_KEY_ID" --url "https://aws.amazon.com"

Service with username + password (piped)

需要用户名+密码的服务（管道传入）

echo 'mypassword' | node CLI vault-store --service docker-hub --type password --username "myuser" --url "https://hub.docker.com"

OAuth token

OAuth令牌

node CLI vault-store --service slack --type oauth --credential-env SLACK_BOT_TOKEN

undefined

node CLI vault-store --service slack --type oauth --credential-env SLACK_BOT_TOKEN

undefined

Retrieve a credential

调取凭证

bash

node CLI vault-get --service <name>

Returns JSON with

service

type

credential

url

username

bash

node CLI vault-get --service <name>

返回包含

service

、

type

、

credential

、

url

、

username

的JSON。

List stored credentials

列出已存储的凭证

bash

node CLI vault-list

Returns a list of services with metadata (without decrypting credential values).

bash

node CLI vault-list

返回带有元数据的服务列表（不会解密凭证值）。

Remove a credential

删除凭证

bash

node CLI vault-remove --service <name>

bash

node CLI vault-remove --service <name>

Update a credential

更新凭证

Run

vault-store

again with the same

--service

name. The existing credential is replaced; the original creation timestamp is preserved.

使用相同的

--service

名称再次执行

vault-store

命令即可，现有凭证会被替换，原始创建时间戳会保留。

4) Making signed git commits

4) 生成签名的git提交

Option A: Use

git-commit

(recommended)

选项A：使用

git-commit

（推荐）

bash

node CLI git-commit --message "feat: implement auth flow"

This creates a commit that is:

SSH-signed with your Ed25519 key
Tagged with trailers linking to your identity and human owner
Logged in your audit trail with a hash-chained signed record
Proof-bundled as a git note for external verification

bash

node CLI git-commit --message "feat: implement auth flow"

生成的提交具备以下特性：

SSH签名 使用你的Ed25519密钥签名
附带trailer标签 关联你的身份和人类所有者
审计日志留存 带有哈希链式签名记录
证明包附加 作为git note可供外部验证

Push commits and proof notes

推送提交和证明笔记

bash

node CLI git-commit --message "feat: implement auth flow" --push

The

--push

flag pushes both the commit and proof notes (handling note ref merging automatically).

bash

node CLI git-commit --message "feat: implement auth flow" --push

--push

参数会同时推送提交和证明笔记（自动处理note引用合并）。

Option B: Normal

git commit

选项B：普通

git commit

Normal

git commit

will work but won't have Alien Agent ID trailers, proof notes, or SSH signing. Use

git-commit

for full provenance.

普通

git commit

可以正常使用，但不会附带Alien Agent ID trailer、证明笔记或SSH签名。如需完整溯源能力，请使用

git-commit

。

GitHub verified badge

GitHub verified徽章

After bootstrap, tell the user:

"To get the 'Verified' badge on GitHub, add this SSH public key to your GitHub account: Go to GitHub → Settings → SSH and GPG keys → New SSH key → Key type: Signing Key"

The SSH public key is shown in the

git-setup

output.

引导完成后，告知用户：

"要在GitHub上获得「Verified」徽章，请将此SSH公钥添加到你的GitHub账户：进入GitHub → 设置 → SSH和GPG密钥 → 新建SSH密钥 → 密钥类型：Signing Key"

SSH公钥会在

git-setup

的输出中展示。

5) Verifying commit provenance

5) 验证提交溯源

bash

node CLI git-verify --commit HEAD

Traces the full chain: SSH signature → agent key → owner binding → SSO attestation.

If the commit has a proof note (from

git-commit

), verification is fully self-contained — works without access to the agent's state directory.

bash

node CLI git-verify --commit HEAD

追溯完整链路：SSH签名 → Agent密钥 → 所有者绑定 → SSO证明。

如果提交附带证明笔记（由

git-commit

生成），验证过程是完全自包含的 —— 无需访问Agent的状态目录即可完成。

6) Signing other operations

6) 其他操作签名

Sign any significant action for the audit trail:

bash

node CLI sign --type TOOL_CALL --action "bash.exec" --payload '{"command":"deploy"}'
node CLI sign --type API_CALL --action "github.create-pr" --payload '{"repo":"foo/bar"}'

对任何重要操作进行签名，留存审计记录：

bash

node CLI sign --type TOOL_CALL --action "bash.exec" --payload '{"command":"deploy"}'
node CLI sign --type API_CALL --action "github.create-pr" --payload '{"repo":"foo/bar"}'

7) Step-by-step bootstrap (manual)

7) 分步引导（手动）

bootstrap

doesn't work for your setup, you can run each step individually:

如果

bootstrap

不适合你的环境，可以单独执行每个步骤：

Step 1: Initialize keypair

步骤1：初始化密钥对

bash

node CLI init

bash

node CLI init

Step 2: Start OIDC authorization

步骤2：启动OIDC授权

bash

node CLI auth --provider-address <PROVIDER_ADDRESS>

This returns JSON containing a

deepLink

and a

qrCode

(Unicode text). Output the

qrCode

value directly in a code block so the user can scan it with the Alien App. Also show the deep link as a fallback:

Scan this QR code with your Alien App:
<qrCode value from JSON>
Or open this link: <deepLink>

bash

node CLI auth --provider-address <PROVIDER_ADDRESS>

返回包含

deepLink

和

qrCode

（Unicode文本）的JSON。将

qrCode

值直接放在代码块中输出，方便用户用Alien App扫描，同时提供深度链接作为备选：

用Alien App扫描此二维码：
<JSON返回的qrCode值>
或打开此链接：<deepLink>

Step 3: Wait for approval

步骤3：等待审批

bash

node CLI bind --no-require-owner-proof

Blocks for up to 5 minutes while the user scans the QR code with Alien App.

bash

node CLI bind --no-require-owner-proof

最长阻塞5分钟，等待用户用Alien App扫描二维码。

Step 4: Configure git signing

步骤4：配置git签名

bash

node CLI git-setup

This writes the SSH key files for commit signing. Tell the user to add the SSH public key (shown in the output) to their GitHub account for verified badges: Go to GitHub → Settings → SSH and GPG keys → New SSH key → Key type: Signing Key.

bash

node CLI git-setup

写入用于提交签名的SSH密钥文件。告知用户将输出中展示的SSH公钥添加到GitHub账户以获取verified徽章：进入GitHub → 设置 → SSH和GPG密钥 → 新建SSH密钥 → 密钥类型：Signing Key。

8) Command reference

8) 命令参考

Command	Purpose	Blocking?
`bootstrap`	One-command setup: init + auth + bind + git-setup	Yes (up to 5 min)
`status`	Check if Alien Agent ID exists and is bound	No
`auth-header [--raw]`	Generate signed auth token for service calls	No
`vault-store --service S --credential C`	Store encrypted credential	No
`vault-get --service S`	Retrieve decrypted credential	No
`vault-list`	List stored credentials (no secrets shown)	No
`vault-remove --service S`	Remove a credential	No
`refresh`	Refresh SSO session tokens	No
`init`	Generate keypair	No
`auth --provider-address <addr>`	Start OIDC auth, get QR code	No
`bind`	Poll for approval, create owner binding	Yes (up to 5 min)
`git-setup`	Write SSH key files for commit signing	No
`git-commit --message "..." [--push]`	Signed commit + trailers + proof note	No
`git-verify [--commit <hash>]`	Verify provenance chain	No
`sign --type T --action A --payload JSON`	Sign operation for audit trail	No
`verify`	Verify state chain integrity	No
`export-proof`	Export proof bundle to stdout	No

命令	用途	是否阻塞？
`bootstrap`	一键设置：初始化 + 认证 + 绑定 + git设置	是（最长5分钟）
`status`	检查Alien Agent ID是否存在并已绑定	否
`auth-header [--raw]`	生成用于服务调用的签名认证令牌	否
`vault-store --service S --credential C`	存储加密凭证	否
`vault-get --service S`	调取解密后的凭证	否
`vault-list`	列出已存储的凭证（不展示密钥）	否
`vault-remove --service S`	删除凭证	否
`refresh`	刷新SSO会话令牌	否
`init`	生成密钥对	否
`auth --provider-address <addr>`	启动OIDC认证，获取二维码	否
`bind`	轮询等待审批，创建所有者绑定	是（最长5分钟）
`git-setup`	写入用于提交签名的SSH密钥文件	否
`git-commit --message "..." [--push]`	签名提交 + trailer + 证明笔记	否
`git-verify [--commit <hash>]`	验证溯源链路	否
`sign --type T --action A --payload JSON`	对操作签名留存审计记录	否
`verify`	验证状态链路完整性	否
`export-proof`	导出证明包到标准输出	否

Common flags

通用参数

Flag	Default	Description
`--state-dir <path>`	`~/.agent-id`	State directory (or `AGENT_ID_STATE_DIR` env)
`--provider-address <addr>`	—	Alien provider address
`--sso-url <url>`	`https://sso.alien-api.com`	SSO base URL
`--raw`	—	Output raw text instead of JSON (auth-header)
`--timeout-sec <n>`	`300`	Poll timeout for `bind`
`--allow-empty`	—	Allow empty commits with `git-commit`
`--push`	—	Push commit and proof notes after `git-commit`
`--remote <name>`	`origin`	Remote to push to (with `--push` )

标志	默认值	描述
`--state-dir <path>`	`~/.agent-id`	状态目录（也可通过 `AGENT_ID_STATE_DIR` 环境变量设置）
`--provider-address <addr>`	—	Alien提供商地址
`--sso-url <url>`	`https://sso.alien-api.com`	SSO基础URL
`--raw`	—	输出原始文本而非JSON（仅auth-header命令）
`--timeout-sec <n>`	`300`	`bind` 命令的轮询超时时间
`--allow-empty`	—	允许 `git-commit` 生成空提交
`--push`	—	`git-commit` 完成后推送提交和证明笔记
`--remote <name>`	`origin`	要推送的远程仓库（配合 `--push` 使用）

9) State directory

9) 状态目录

~/.agent-id/
├── keys/main.json             # Ed25519 keypair (mode 0600)
├── ssh/
│   ├── agent-id               # SSH private key (mode 0600)
│   ├── agent-id.pub           # SSH public key
│   └── allowed_signers        # For git signature verification
├── vault/
│   ├── github.json            # Encrypted credential (mode 0600)
│   ├── slack.json
│   └── ...
├── audit/operations.jsonl     # Hash-chained signed operation log
├── owner-binding.json         # Owner binding (human ↔ agent link)
├── owner-session.json         # Session tokens (mode 0600) — NEVER commit
├── nonces.json                # Per-agent nonce tracking
├── sequence.json              # Sequence counter

~/.agent-id/
├── keys/main.json             # Ed25519密钥对（权限0600）
├── ssh/
│   ├── agent-id               # SSH私钥（权限0600）
│   ├── agent-id.pub           # SSH公钥
│   └── allowed_signers        # 用于git签名验证
├── vault/
│   ├── github.json            # 加密凭证（权限0600）
│   ├── slack.json
│   └── ...
├── audit/operations.jsonl     # 哈希链式签名操作日志
├── owner-binding.json         # 所有者绑定（人类 ↔ Agent关联）
├── owner-session.json         # 会话令牌（权限0600）—— 严禁提交到代码仓库
├── nonces.json                # Agent维度的nonce跟踪
├── sequence.json              # 序列计数器

10) Integration patterns

10) 集成模式

Claude Code (CLAUDE.md)

Before making your first git commit, run: node /path/to/cli.mjs bootstrap

在第一次git提交前，请执行：node /path/to/cli.mjs bootstrap

Environment variables

环境变量

bash

export ALIEN_PROVIDER_ADDRESS="00000003..."
export AGENT_ID_STATE_DIR="~/.agent-id"

bash

export ALIEN_PROVIDER_ADDRESS="00000003..."
export AGENT_ID_STATE_DIR="~/.agent-id"

CI/CD (GitHub Actions)

yaml

- name: Bootstrap agent identity
  env:
    ALIEN_PROVIDER_ADDRESS: ${{ secrets.ALIEN_PROVIDER_ADDRESS }}
  run: node /path/to/cli.mjs bootstrap

yaml

- name: Bootstrap agent identity
  env:
    ALIEN_PROVIDER_ADDRESS: ${{ secrets.ALIEN_PROVIDER_ADDRESS }}
  run: node /path/to/cli.mjs bootstrap

11) Error handling

11) 错误处理

Error	Action
`No provider address`	Set `--provider-address` , env var, or `default-provider.txt`
`No pending auth found`	Run `auth` or `bootstrap`
`Alien SSO authorization session expired`	Run `bootstrap` again
`User rejected Alien SSO authorization`	Ask user to try again
`Timed out waiting`	Run `bootstrap` again, remind user to scan promptly
`No agent keypair`	Run `bootstrap` or `init`
`No credential stored for "..."`	Ask user for the credential, then `vault-store`

错误	处理方式
`No provider address`	设置 `--provider-address` 参数、环境变量，或配置 `default-provider.txt`
`No pending auth found`	执行 `auth` 或 `bootstrap` 命令
`Alien SSO authorization session expired`	重新执行 `bootstrap` 命令
`User rejected Alien SSO authorization`	请用户重试
`Timed out waiting`	重新执行 `bootstrap` 命令，提醒用户及时扫码
`No agent keypair`	执行 `bootstrap` 或 `init` 命令
`No credential stored for "..."`	请用户提供凭证，然后执行 `vault-store`

12) Security

12) 安全说明

Private keys stored with 0600 permissions — never transmitted
Vault credentials encrypted with AES-256-GCM (key derived via HKDF from agent's Ed25519 key)
PKCE prevents authorization code interception
Auth tokens are short-lived (5 minute validity)
Hash-chained audit log — any tampering breaks the chain
Ed25519 SSH signatures on commits provide non-repudiation
Never expose
```
owner-session.json
```
or vault files

私钥以0600权限存储 —— 永远不会对外传输
保管库凭证使用AES-256-GCM加密（密钥通过HKDF从Agent的Ed25519密钥派生）
PKCE机制防止授权码拦截
认证令牌有效期短（仅5分钟）
哈希链式审计日志 —— 任何篡改都会破坏链路完整性
提交使用Ed25519 SSH签名，提供不可否认性
永远不要暴露
```
owner-session.json
```
或保管库文件

alien-agent-id

Original

Translation

Alien Agent ID — Identity, Authentication & Credentials for AI Agents

Alien Agent ID — AI Agent的身份、认证与凭证管理

Quick Start

快速开始

Prerequisites

前置要求

Resolve the CLI path first

先解析CLI路径

1) When to use

1) 适用场景

Step 2: Choose provider and start authentication

第2步：选择提供商并开始认证

Get the auth header for curl

获取curl用的auth header

External services (vault credentials)

外部服务（保管库凭证）

Retrieve a stored credential

调取已存储的凭证

GitHub API

GitHub API

Or more simply using jq if available

如果安装了jq可以使用更简单的写法

3) Credential vault

3) 凭证保管库

Storing credentials — the human-agent flow

存储凭证 —— 人类-Agent交互流程

Option A: from file (most secure — secret never on command line)

选项A：从文件读取（最安全 —— 密钥不会出现在命令行中）

Then clean up the temp file:

随后清理临时文件：

Option B: from environment variable

选项B：从环境变量读取

Option C: piped via stdin (secret not in process list)

选项C：通过stdin管道传入（不会出现在进程列表中）

Last resort: direct argument (visible in process list)

最后方案：直接作为参数传入（会在进程列表中可见）

Store examples

存储示例

GitHub personal access token (from file)

GitHub个人访问令牌（从文件读取）

AWS credentials (from env)

AWS凭证（从环境变量读取）

Service with username + password (piped)

需要用户名+密码的服务（管道传入）

OAuth token

OAuth令牌

Retrieve a credential

调取凭证

List stored credentials

列出已存储的凭证

Remove a credential

删除凭证

Update a credential

更新凭证

4) Making signed git commits

4) 生成签名的git提交

Option A: Use git-commit (recommended)

选项A：使用git-commit（推荐）

Push commits and proof notes

推送提交和证明笔记

Option B: Normal git commit

选项B：普通git commit

GitHub verified badge

GitHub verified徽章

5) Verifying commit provenance

5) 验证提交溯源

6) Signing other operations

6) 其他操作签名

7) Step-by-step bootstrap (manual)

7) 分步引导（手动）

Step 1: Initialize keypair

步骤1：初始化密钥对

Step 2: Start OIDC authorization

步骤2：启动OIDC授权

Step 3: Wait for approval

步骤3：等待审批

Step 4: Configure git signing

Option A: Use
`git-commit`
(recommended)

选项A：使用
`git-commit`
（推荐）

Option B: Normal
`git commit`

选项B：普通
`git commit`