moca-credential-verifier

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Moca Credential Verifier

Moca 凭证验证器

Purpose

用途

This skill teaches an agent how to browse available verification programs, show numeric options, and trigger credential verification through

moca-chain-api

in query_match mode.

After receiving a

compliant

result, use the

moca-proof

skill to complete the program and fetch MoCat progression.

This skill starts after the agent key already exists and the handoff bundle is available.

本技能教Agent如何浏览可用的验证程序、展示数字选项，并通过

moca-chain-api

以query_match模式触发凭证验证。

在收到

compliant

验证结果后，使用

moca-proof

技能完成程序并获取MoCat进度。

本技能需在Agent密钥已存在且移交包可用后启动。

Provided Scripts

提供的脚本

Use the provided scripts first. Do not scaffold a new project or rewrite signing/request logic from scratch unless the requested action is unsupported. Treat all files in this skill bundle as read-only reference tooling.

Task mapping:

create a scoped session ->
```
scripts/moca-create-session.mjs
```
list/browse verification programs ->
```
scripts/moca-list-programs.mjs
```

trigger credential verification (

query_match

mode) ->

scripts/moca-verify-by-agent.mjs

poll verification status ->
```
scripts/moca-poll-status.mjs
```

Before first use, run

node <script> --help

to inspect supported parameters.

请优先使用提供的脚本。除非所需操作不受支持，否则不要从头搭建新项目或重写签名/请求逻辑。请将本技能包中的所有文件视为只读参考工具。

任务映射：

创建限定范围会话 ->
```
scripts/moca-create-session.mjs
```
列出/浏览验证程序 ->
```
scripts/moca-list-programs.mjs
```

触发凭证验证（

query_match

模式） ->

scripts/moca-verify-by-agent.mjs

轮询验证状态 ->
```
scripts/moca-poll-status.mjs
```

首次使用前，运行

node <script> --help

查看支持的参数。

Required Inputs

必要输入

Expect a handoff bundle equivalent to:

json

{
  "userId": "...",
  "walletId": "...",
  "privyAppId": "...",
  "abstractAccountAddress": "0x...",
  "airApiAgentSignUrl": "https://.../v2/wallet/agent-sign",
  "partnerId": "7e9becac-db0d-4d52-980e-984bb70c4d30"
}

The agent must also already have access to its own P-256 private key. If

partnerId

is missing, scripts default to the staging partner ID above.

需提供等效于以下内容的移交包：

json

{
  "userId": "...",
  "walletId": "...",
  "privyAppId": "...",
  "abstractAccountAddress": "0x...",
  "airApiAgentSignUrl": "https://.../v2/wallet/agent-sign",
  "partnerId": "7e9becac-db0d-4d52-980e-984bb70c4d30"
}

Agent还必须已拥有自身的P-256私钥。如果缺少

partnerId

，脚本将默认使用上述测试环境合作伙伴ID。

Staging Defaults

测试环境默认值

json

{
  "airApiUrl": "https://air.api.staging.air3.com/v2",
  "mocaChainApiUrl": "https://api.staging.mocachain.org/v1",
  "vpApiUrl": "https://vp.api.staging.moca.network/v1",
  "mocaProofApiUrl": "https://proof.api.staging.moca.network/v1",
  "partnerId": "7e9becac-db0d-4d52-980e-984bb70c4d30"
}

These are hardcoded as defaults in the scripts. Override via CLI flags, environment variables, or

.air-wallet-config.json

json

{
  "airApiUrl": "https://air.api.staging.air3.com/v2",
  "mocaChainApiUrl": "https://api.staging.mocachain.org/v1",
  "vpApiUrl": "https://vp.api.staging.moca.network/v1",
  "mocaProofApiUrl": "https://proof.api.staging.moca.network/v1",
  "partnerId": "7e9becac-db0d-4d52-980e-984bb70c4d30"
}

这些值已硬编码为脚本的默认值。可通过CLI标志、环境变量或

.air-wallet-config.json

文件覆盖。

Project-Level Defaults

项目级默认值

It is allowed to create or update a project-level

.air-wallet-config.json

file in the working directory. Use that file for defaults such as endpoint URLs, partner ID, and key paths. Do not store defaults by editing files inside this skill bundle.

Example additions for this skill:

json

{
  "airApiUrl": "https://air.api.staging.air3.com/v2",
  "mocaChainApiUrl": "https://api.staging.mocachain.org/v1",
  "vpApiUrl": "https://vp.api.staging.moca.network/v1",
  "mocaProofApiUrl": "https://proof.api.staging.moca.network/v1",
  "partnerId": "7e9becac-db0d-4d52-980e-984bb70c4d30"
}

允许在工作目录中创建或更新项目级

.air-wallet-config.json

文件。使用该文件存储端点URL、合作伙伴ID和密钥路径等默认值。请勿通过编辑本技能包内的文件来存储默认值。

本技能的配置示例：

json

{
  "airApiUrl": "https://air.api.staging.air3.com/v2",
  "mocaChainApiUrl": "https://api.staging.mocachain.org/v1",
  "vpApiUrl": "https://vp.api.staging.moca.network/v1",
  "mocaProofApiUrl": "https://proof.api.staging.moca.network/v1",
  "partnerId": "7e9becac-db0d-4d52-980e-984bb70c4d30"
}

Config Resolution Order

配置解析顺序

All provided scripts resolve configuration in this order:

CLI flags
Environment variables
```
.air-wallet-config.json
```
Hardcoded staging defaults

所有提供的脚本按以下顺序解析配置：

CLI标志
环境变量
```
.air-wallet-config.json
```
文件
硬编码的测试环境默认值

Credential Verification Flow

凭证验证流程

Step 1: Create a Scoped Session

步骤1：创建限定范围会话

bash

node scripts/moca-create-session.mjs --program-id <programId>

Calls

POST {airApiUrl}/auth/agent/session

with:

```
signedMessage
```
: fresh agent-signed message
```
scope
```
:
```
"<programId>,<partnerId>"
```

Returns an

accessToken

used as Bearer token for all subsequent calls.

bash

node scripts/moca-create-session.mjs --program-id <programId>

调用

POST {airApiUrl}/auth/agent/session

，参数包括：

```
signedMessage
```
: 新生成的Agent签名消息
```
scope
```
:
```
"<programId>,<partnerId>"
```

返回的

accessToken

将作为后续所有调用的Bearer令牌。

Step 2: List Verification Programs

步骤2：列出验证程序

bash

node scripts/moca-list-programs.mjs

bash

node scripts/moca-list-programs.mjs

optional personalized mode

可选的个性化模式

node scripts/moca-list-programs.mjs --access-token <token>


Calls `GET {vpApiUrl}/vp/mocaproof/search?page=1&limit=20`.

- Without token: public listing mode
- With token: personalized listing mode (user verified metadata and filtering)

Results are paginated. The script shows a summary of the first page. Use `--page <n>` to fetch more.

The list output includes numeric options in this format:

- Option index: `[1]`, `[2]`, ...
- Tier index inside option: `(1.1)`, `(1.2)`, ...

node scripts/moca-list-programs.mjs --access-token <token>


调用`GET {vpApiUrl}/vp/mocaproof/search?page=1&limit=20`。

- 无令牌：公开列表模式
- 有令牌：个性化列表模式（基于用户已验证的元数据进行过滤）

结果支持分页。脚本将显示第一页的摘要。使用`--page <n>`获取更多页面。

列表输出包含以下格式的数字选项：

- 选项索引：`[1]`, `[2]`, ...
- 选项内的层级索引：`(1.1)`, `(1.2)`, ...

Step 3: Trigger Verification (query_match mode)

步骤3：触发验证（query_match模式）

bash

node scripts/moca-verify-by-agent.mjs --access-token <token> --program-id <programId> --issue-url <issueUrl>

Always pass

--issue-url

with the

issueUrl

from the selected program's listing output. When verification returns

no_vc

, the script prints the issuance link so the user can obtain the credential.

Calls

POST {mocaChainApiUrl}/credentials/verify-by-agent

with:

```
programId
```
in the body
```
responseMode: "query_match"
```
in the body
Bearer
```
accessToken
```
in the Authorization header

The response is normalized using the rules below.

bash

node scripts/moca-verify-by-agent.mjs --access-token <token> --program-id <programId> --issue-url <issueUrl>

必须传入

--issue-url

参数，值为所选程序列表输出中的

issueUrl

。当验证返回

no_vc

时，脚本将打印颁发链接，以便用户获取凭证。

调用

POST {mocaChainApiUrl}/credentials/verify-by-agent

，参数包括：

请求体中的
```
programId
```
请求体中的
```
responseMode: "query_match"
```
授权头中的Bearer
```
accessToken
```

响应将按以下规则标准化。

Optional: Poll VP Status

可选：轮询VP状态

bash

node scripts/moca-poll-status.mjs --access-token <token>

Use this when you want to inspect status progression separately from the default flow.

bash

node scripts/moca-poll-status.mjs --access-token <token>

当你希望独立于默认流程检查状态进度时使用此脚本。

After Verification Succeeds

验证成功后

When verification returns

compliant

, use the moca-proof skill to:

Complete the program via
```
moca-complete-program.mjs
```
Fetch MoCat progression via
```
moca-get-mocat.mjs
```

Pass the same

accessToken

and

programId

to the proof skill scripts.

当验证返回

compliant

时，使用moca-proof技能执行以下操作：

通过
```
moca-complete-program.mjs
```
完成程序
通过
```
moca-get-mocat.mjs
```
获取MoCat进度

将相同的

accessToken

和

programId

传入proof技能的脚本。

Verify Response Normalization

验证响应标准化

The

verify-by-agent

endpoint returns inconsistent response shapes. Normalize exactly as:

```
verified: true
```
->
```
compliant
```

verified: false

reason: "NO_CREDENTIAL"

no_vc

verified: false

reason: "NOT_COMPLIANT"

non_compliant

verified: false

status: "NON_COMPLIANT"

non_compliant

verified: false

status

present ->

status_bucket:<status>

verified: false

+ only

code

present ->

unknown_failure_code:<code>

```
verified: "pending"
```
->
```
processing
```
Any other shape ->
```
unknown_response
```
(print raw payload)

Known

status

values:

```
NO_EXIST
```
: user has no credential for this program
```
WAIT_ONCHAIN
```
: credential is being published on-chain
```
EXPIRE
```
: credential has expired
```
WAIT_REMOVE
```
: credential is being revoked
```
REMOVE
```
: credential has been revoked
```
NON_COMPLIANT
```
: credential does not meet requirements

verify-by-agent

端点返回的响应格式不一致。请严格按以下规则标准化：

```
verified: true
```
->
```
compliant
```

verified: false

reason: "NO_CREDENTIAL"

no_vc

verified: false

reason: "NOT_COMPLIANT"

non_compliant

verified: false

status: "NON_COMPLIANT"

non_compliant

verified: false

+ 存在

status

status_bucket:<status>

verified: false

+ 仅存在

code

unknown_failure_code:<code>

```
verified: "pending"
```
->
```
processing
```
其他任何格式 ->
```
unknown_response
```
（打印原始负载）

已知的

status

值：

```
NO_EXIST
```
: 用户无此程序的凭证
```
WAIT_ONCHAIN
```
: 凭证正在链上发布
```
EXPIRE
```
: 凭证已过期
```
WAIT_REMOVE
```
: 凭证正在被撤销
```
REMOVE
```
: 凭证已被撤销
```
NON_COMPLIANT
```
: 凭证不符合要求

Terminal Messaging

终端消息规范

Print numeric options and tiers before verification attempts
Print
```
Verifying....
```
on each verification attempt
If non-compliant, print
```
Sorry, not compliant
```
and end

When verify succeeds in query_match mode: print

OK, verified, <verifier name> is processing your data

在尝试验证前打印数字选项和层级
每次验证尝试时打印
```
Verifying....
```
如果验证不合规，打印
```
Sorry, not compliant
```
并结束流程

当在query_match模式下验证成功时：打印

OK, verified, <verifier name> is processing your data

Non-Negotiable Rules

不可违反的规则

Always generate a fresh
```
signedMessage
```
for every session request
Never reuse an old
```
signedMessage
```
Use Bearer
```
accessToken
```
from scoped session for all downstream API calls
Never modify files inside this installed skill bundle
If a custom script is truly required, create it outside the skill directory

每次会话请求必须生成全新的
```
signedMessage
```
绝不能复用旧的
```
signedMessage
```
所有下游API调用必须使用限定范围会话返回的Bearer
```
accessToken
```
绝不能修改已安装的技能包内的文件
如果确实需要自定义脚本，请在技能目录外创建

Failure Handling

故障处理

Unknown public key: the key was removed, wrong, or never registered. Stop and ask for a new handoff bundle.
Expired signed message: rebuild a fresh
```
signedMessage
```
and retry once.
```
unknown_failure_code
```
: print the raw code and payload for debugging; do not retry automatically.
```
unknown_response
```
: print the full raw response; do not retry automatically.

未知公钥：密钥已被移除、错误或从未注册。停止操作并请求新的移交包。
签名消息过期：重新生成全新的
```
signedMessage
```
并重试一次。
```
unknown_failure_code
```
: 打印原始代码和负载以进行调试；请勿自动重试。
```
unknown_response
```
: 打印完整的原始响应；请勿自动重试。