BEEOS CLOUD / DEVELOPER REFERENCE

身份与请求签名

Ed25519 密钥对、请求签名头与规范化哈希。

harness 持有一对 Ed25519 密钥。SDK 负责构造发往 Agent Gateway 请求的精确签名原文和四个 X-Agent-* 头；私钥不会离开你的进程。

AgentRequestIdentity

TypeScript @beeos-ai/cloud-harness-sdk · 仅 TypeScript

一个公钥加一个签名函数。私钥由宿主保管，SDK 负责构造精确的签名原文。

interface AgentRequestIdentity

属性

名称	类型	说明
`publicKey`	`Uint8Array`	原始 32 字节 Ed25519 公钥；以 base64 形式放入 `X-Agent-Public-Key`。

sign

对消息签名并返回原始 Ed25519 签名；私钥始终留在该函数内部。

sign(message: Uint8Array): Uint8Array

TypeScript · 参数

参数	类型	必填	默认值	说明
`message`	`Uint8Array`	是		要签名的原始字节。

返回值 Uint8Array

agentAuthHeaders

TypeScript @beeos-ai/cloud-harness-sdk · Python beeos_cloud_harness_sdk.identity

为你自己发送的请求（例如 WebSocket 升级）构造四个 X-Agent-* 头。

function agentAuthHeaders(method: string, urlPath: string, keys: AgentKeyPair, body?: string | Uint8Array | null): Record<string, string>

TypeScript · 参数

参数	类型	必填	说明
`method`	`string`	是	HTTP 方法，在签名原文中会转为大写。
`urlPath`	`string`	是	参与签名的已解码请求路径，必须与服务端看到的路径一致，且不能带查询串。
`keys`	AgentKeyPair	是	为请求签名的 harness 密钥对。
`body`	`string \| Uint8Array \| null`	否	请求体原文；`null` 或省略表示空请求体。

返回值 Record<string, string>

Python · 参数

参数	类型	必填	默认值	说明
`method`	`str`	是		HTTP 方法，在签名原文中会转为大写。
`url_path`	`str`	是		参与签名的已解码请求路径，必须与服务端看到的路径一致，且不能带查询串。
`keys`	AgentKeyPair	是		为请求签名的 harness 密钥对。
`body`	`bytes \| str \| None`	否	`None`	请求体原文；`null` 或省略表示空请求体。

返回值 dict[str, str]

agentIdentityFromKeyPair

TypeScript @beeos-ai/cloud-harness-sdk · 仅 TypeScript

把密钥对包装成 AgentRequestIdentity。带签名的 Gateway 请求和注册证明都使用它。

function agentIdentityFromKeyPair(keys: AgentKeyPair): AgentRequestIdentity

TypeScript · 参数

参数	类型	必填	默认值	说明
`keys`	AgentKeyPair	是		用其私钥签名的密钥对。

返回值 AgentRequestIdentity

agentRequestAuthHeaders

TypeScript @beeos-ai/cloud-harness-sdk · 仅 TypeScript

function agentRequestAuthHeaders(method: string, path: string, identity: AgentRequestIdentity, body?: string | Uint8Array | null, now: () => number = Date.now, nonce: () => string = randomUUID): Record<string, string>

TypeScript · 参数

参数	类型	必填	默认值	说明
`method`	`string`	是		HTTP 方法，在签名原文中会转为大写。
`path`	`string`	是		参与签名的已解码请求路径。
`identity`	AgentRequestIdentity	是		为请求签名的身份。
`body`	`string \| Uint8Array \| null`	否		请求体原文；`null` 或省略表示空请求体。
`now`	`() => number`	否	`Date.now`	毫秒时钟，测试时可替换，默认 `Date.now`。
`nonce`	`() => string`	否	`randomUUID`	随机数（nonce）生成函数，测试时可替换，默认 `randomUUID`。

返回值 Record<string, string>

authenticatedAgentFetch

TypeScript @beeos-ai/cloud-harness-sdk · 仅 TypeScript

发送带签名的 fetch 请求：对解码后的 URL 路径和请求体原文签名，拒绝重定向，响应来自其他源时抛错。

async function authenticatedAgentFetch(input: string | URL, identity: AgentRequestIdentity, init?: RequestInit): Promise<Response>

TypeScript · 参数

参数	类型	必填	说明
`input`	`string \| URL`	是	请求的绝对 URL。
`identity`	AgentRequestIdentity	是	为请求签名的身份。
`init`	`RequestInit`	否	标准 `fetch` 选项。请求体必须是字符串或 `Uint8Array`，以保证签名覆盖原始字节。

返回值 Promise<Response>

bodyHashHex

TypeScript @beeos-ai/cloud-harness-sdk · Python beeos_cloud_harness_sdk.identity

返回请求体 SHA-256 的小写十六进制；空或缺省请求体得到 EMPTY_BODY_SHA256。

function bodyHashHex(body?: string | Uint8Array | null): string

TypeScript · 参数

参数	类型	必填	默认值	说明
`body`	`string \| Uint8Array \| null`	否		请求体；字符串按 UTF-8 计算哈希。

返回值 string

Python · 参数

参数	类型	必填	默认值	说明
`body`	`bytes \| str \| None`	否	`None`	请求体；字符串按 UTF-8 计算哈希。

返回值 str

canonicalize_jcs

Python beeos_cloud_harness_sdk.jcs · 仅 Python

把 JSON 值序列化为规范形式（RFC 8785 JSON Canonicalization Scheme），即身份证明所哈希的字节级精确文本。

def canonicalize_jcs(value: Any) -> str

Python · 参数

参数	类型	必填	默认值	说明
`value`	`Any`	是		与 JSON 兼容的值：dict、list、str、int、float、bool 或 None。

返回值 str

generate_agent_key_pair

Python beeos_cloud_harness_sdk.identity · 仅 Python

生成新的 Ed25519 密钥对，并以 JSON 写入 save_to，文件权限为 0600。

def generate_agent_key_pair(save_to: str | Path) -> AgentKeyPair

Python · 参数

参数	类型	必填	默认值	说明
`save_to`	`str \| Path`	是		密钥文件路径，缺失的父目录会被创建。

返回值 AgentKeyPair

loadAgentKeyPair

TypeScript @beeos-ai/cloud-harness-sdk · Python beeos_cloud_harness_sdk.identity

加载密钥文件。文件不存在时，TypeScript 会创建新密钥对（权限 0600）；Python 仅在设置 create_if_missing 时创建。文件内容是含 publicKey 与 privateKey 的 JSON，或单独的 base64 32 字节种子。

function loadAgentKeyPair(filePath: string): AgentKeyPair

TypeScript · 参数

参数	类型	必填	默认值	说明
`filePath`	`string`	是		密钥文件路径。内容为含 base64 `publicKey` 与 `privateKey` 的 JSON，或单独的 base64 32 字节种子。

返回值 AgentKeyPair

Python · 参数

参数	类型	必填	默认值	说明
`file_path`	`str \| Path`	是		密钥文件路径。内容为含 base64 `publicKey` 与 `privateKey` 的 JSON，或单独的 base64 32 字节种子。
`create_if_missing`	`bool`	否	`False`	为 `True` 时文件不存在就生成新密钥对并创建；否则抛出 `FileNotFoundError`。

返回值 AgentKeyPair

runtime_domain_hash

Python beeos_cloud_harness_sdk.jcs · 仅 Python

返回域字符串、换行符与载荷规范 JSON 拼接后的 SHA-256（十六进制）。它是身份证明所用的哈希。

def runtime_domain_hash(domain: str, payload: Any) -> str

Python · 参数

参数	类型	必填	默认值	说明
`domain`	`str`	是		域分隔字符串，例如 `REGISTRATION_HASH_DOMAIN`。
`payload`	`Any`	是		要哈希的、与 JSON 兼容的载荷。

返回值 str

sha256_hex

Python beeos_cloud_harness_sdk.jcs · 仅 Python

返回输入的 SHA-256 摘要（小写十六进制）。

def sha256_hex(data: str | bytes) -> str

Python · 参数

参数	类型	必填	默认值	说明
`data`	`str \| bytes`	是		文本（按 UTF-8 哈希）或字节。

返回值 str

signAgentMessage

TypeScript @beeos-ai/cloud-harness-sdk · Python beeos_cloud_harness_sdk.identity

用原始 Ed25519 私钥对消息签名，返回 64 字节签名。

function signAgentMessage(message: string | Uint8Array, privateKey: Uint8Array): Uint8Array

TypeScript · 参数

参数	类型	必填	默认值	说明
`message`	`string \| Uint8Array`	是		要签名的消息，字符串按 UTF-8 编码。
`privateKey`	`Uint8Array`	是		原始 32 字节 Ed25519 种子（也接受 PKCS#8 DER 私钥）。

返回值 Uint8Array

Python · 参数

参数	类型	必填	默认值	说明
`message`	`str`	是		要签名的消息，字符串按 UTF-8 编码。
`private_key`	`bytes`	是		原始 32 字节 Ed25519 种子（也接受 PKCS#8 DER 私钥）。

返回值 bytes

signing_path_from_url

Python beeos_cloud_harness_sdk.identity · 仅 Python

返回 URL 解码后的路径，即要签名的路径。URL 带查询串时抛出 ValueError。

def signing_path_from_url(url: str) -> str

Python · 参数

参数	类型	必填	默认值	说明
`url`	`str`	是		绝对 URL，不能带查询串。

返回值 str

AGENT_PROJECTION_HASH_DOMAIN

Python beeos_cloud_harness_sdk.jcs · 仅 Python

智能体投影哈希所用的域字符串 beeos.runtime.agent-projection.v1。

AGENT_PROJECTION_HASH_DOMAIN = 'beeos.runtime.agent-projection.v1'

EMPTY_BODY_SHA256

TypeScript @beeos-ai/cloud-harness-sdk · Python beeos_cloud_harness_sdk.identity

空请求体的 SHA-256（十六进制）。

const EMPTY_BODY_SHA256: "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"

HEARTBEAT_HASH_DOMAIN

Python beeos_cloud_harness_sdk.jcs · 仅 Python

心跳身份证明所用的域字符串 beeos.runtime.heartbeat.v1。

HEARTBEAT_HASH_DOMAIN = 'beeos.runtime.heartbeat.v1'

REGISTRATION_HASH_DOMAIN

Python beeos_cloud_harness_sdk.jcs · 仅 Python

注册身份证明所用的域字符串 beeos.runtime.registration.v1。

REGISTRATION_HASH_DOMAIN = 'beeos.runtime.registration.v1'

BeeOS Cloud返回文档首页