BEEOS CLOUD / DEVELOPER REFERENCE

Identity and request signing

Ed25519 key pairs, signed request headers, and canonical hashing.

The harness owns an Ed25519 key pair. The SDK builds the exact signing preimage and the four X-Agent-* headers for Agent Gateway requests; the key never leaves your process.

AgentRequestIdentity

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

A public key plus a signing function. The host keeps the private key; the SDK builds the exact signing preimage.

interface AgentRequestIdentity

Properties

Name	Type	Description
`publicKey`	`Uint8Array`	Raw 32-byte Ed25519 public key; it is sent base64-encoded in `X-Agent-Public-Key`.

sign

Signs a message and returns the raw Ed25519 signature. The private key stays inside this function.

sign(message: Uint8Array): Uint8Array

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`message`	`Uint8Array`	yes		The exact bytes to sign.

Returns Uint8Array

agentAuthHeaders

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

Builds the four X-Agent-* headers for a request that you send yourself, for example a WebSocket upgrade.

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

TypeScript · Parameters

Parameter	Type	Required	Description
`method`	`string`	yes	HTTP method; it is upper-cased in the signing preimage.
`urlPath`	`string`	yes	Decoded request path that is signed. It must match the path the server sees and must not contain a query string.
`keys`	AgentKeyPair	yes	The harness key pair that signs the request.
`body`	`string \| Uint8Array \| null`	no	Exact request body; `null` or omitted means an empty body.

Returns Record<string, string>

Python · Parameters

Parameter	Type	Required	Default	Description
`method`	`str`	yes		HTTP method; it is upper-cased in the signing preimage.
`url_path`	`str`	yes		Decoded request path that is signed. It must match the path the server sees and must not contain a query string.
`keys`	AgentKeyPair	yes		The harness key pair that signs the request.
`body`	`bytes \| str \| None`	no	`None`	Exact request body; `null` or omitted means an empty body.

Returns dict[str, str]

agentIdentityFromKeyPair

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

Wraps a key pair into an AgentRequestIdentity. Signed Gateway requests and registration proofs use it.

function agentIdentityFromKeyPair(keys: AgentKeyPair): AgentRequestIdentity

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`keys`	AgentKeyPair	yes		The key pair whose private key signs.

Returns AgentRequestIdentity

agentRequestAuthHeaders

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

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

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`method`	`string`	yes		HTTP method; it is upper-cased in the signing preimage.
`path`	`string`	yes		Decoded request path that is signed.
`identity`	AgentRequestIdentity	yes		The identity that signs the request.
`body`	`string \| Uint8Array \| null`	no		Exact request body; `null` or omitted means an empty body.
`now`	`() => number`	no	`Date.now`	Clock in milliseconds; replace it in tests. Defaults to `Date.now`.
`nonce`	`() => string`	no	`randomUUID`	Nonce generator; replace it in tests. Defaults to `randomUUID`.

Returns Record<string, string>

authenticatedAgentFetch

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

Sends a signed fetch request. It signs the decoded URL path and the exact body, refuses redirects, and rejects when the response comes from another origin.

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

TypeScript · Parameters

Parameter	Type	Required	Description
`input`	`string \| URL`	yes	Absolute URL of the request.
`identity`	AgentRequestIdentity	yes	The identity that signs the request.
`init`	`RequestInit`	no	Standard `fetch` options. A body must be a string or a `Uint8Array` so that the signature covers the exact bytes.

Returns Promise<Response>

bodyHashHex

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

Returns the lowercase hexadecimal SHA-256 of a request body; an empty or missing body hashes to EMPTY_BODY_SHA256.

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

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`body`	`string \| Uint8Array \| null`	no		Request body; strings are hashed as UTF-8.

Returns string

Python · Parameters

Parameter	Type	Required	Default	Description
`body`	`bytes \| str \| None`	no	`None`	Request body; strings are hashed as UTF-8.

Returns str

canonicalize_jcs

Python beeos_cloud_harness_sdk.jcs · Python only

Serialises a JSON value to its canonical form (RFC 8785, JSON Canonicalization Scheme), the byte-exact text that is hashed for identity proofs.

def canonicalize_jcs(value: Any) -> str

Python · Parameters

Parameter	Type	Required	Default	Description
`value`	`Any`	yes		A JSON-compatible value: dict, list, str, int, float, bool or None.

Returns str

generate_agent_key_pair

Python beeos_cloud_harness_sdk.identity · Python only

Generates a new Ed25519 key pair and writes it as JSON to save_to with mode 0600.

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

Python · Parameters

Parameter	Type	Required	Default	Description
`save_to`	`str \| Path`	yes		Path of the key file; missing parent directories are created.

Returns AgentKeyPair

loadAgentKeyPair

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

Loads the key file. A missing file is created with a new key pair (mode 0600) in TypeScript; in Python it is created only when create_if_missing is set. A file holds JSON with publicKey and privateKey, or a bare base64 32-byte seed.

function loadAgentKeyPair(filePath: string): AgentKeyPair

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`filePath`	`string`	yes		Path of the key file. It holds either JSON with base64 `publicKey` and `privateKey`, or a bare base64 32-byte seed.

Returns AgentKeyPair

Python · Parameters

Parameter	Type	Required	Default	Description
`file_path`	`str \| Path`	yes		Path of the key file. It holds either JSON with base64 `publicKey` and `privateKey`, or a bare base64 32-byte seed.
`create_if_missing`	`bool`	no	`False`	When `True`, a missing file is created with a new key pair; otherwise `FileNotFoundError` is raised.

Returns AgentKeyPair

runtime_domain_hash

Python beeos_cloud_harness_sdk.jcs · Python only

Returns the SHA-256 (hexadecimal) of the domain string, a line feed, and the canonical JSON of the payload. It is the hash used in identity proofs.

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

Python · Parameters

Parameter	Type	Required	Default	Description
`domain`	`str`	yes		Domain-separation string, for example `REGISTRATION_HASH_DOMAIN`.
`payload`	`Any`	yes		JSON-compatible payload to hash.

Returns str

sha256_hex

Python beeos_cloud_harness_sdk.jcs · Python only

Returns the lowercase hexadecimal SHA-256 digest of the input.

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

Python · Parameters

Parameter	Type	Required	Default	Description
`data`	`str \| bytes`	yes		Text (hashed as UTF-8) or bytes.

Returns str

signAgentMessage

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

Signs a message with a raw Ed25519 private key and returns the 64-byte signature.

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

TypeScript · Parameters

Parameter	Type	Required	Default	Description
`message`	`string \| Uint8Array`	yes		Message to sign; strings are encoded as UTF-8.
`privateKey`	`Uint8Array`	yes		Raw 32-byte Ed25519 seed (a PKCS#8 DER key is also accepted).

Returns Uint8Array

Python · Parameters

Parameter	Type	Required	Default	Description
`message`	`str`	yes		Message to sign; strings are encoded as UTF-8.
`private_key`	`bytes`	yes		Raw 32-byte Ed25519 seed (a PKCS#8 DER key is also accepted).

Returns bytes

signing_path_from_url

Python beeos_cloud_harness_sdk.identity · Python only

Returns the decoded path of a URL, which is the path to sign. Raises ValueError when the URL has a query string.

def signing_path_from_url(url: str) -> str

Python · Parameters

Parameter	Type	Required	Default	Description
`url`	`str`	yes		Absolute URL; it must not contain a query string.

Returns str

AGENT_PROJECTION_HASH_DOMAIN

Python beeos_cloud_harness_sdk.jcs · Python only

Domain string beeos.runtime.agent-projection.v1 for the agent-projection hash.

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 of the empty body, in hexadecimal.

const EMPTY_BODY_SHA256: "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"

HEARTBEAT_HASH_DOMAIN

Python beeos_cloud_harness_sdk.jcs · Python only

Domain string beeos.runtime.heartbeat.v1 for heartbeat identity proofs.

HEARTBEAT_HASH_DOMAIN = 'beeos.runtime.heartbeat.v1'

REGISTRATION_HASH_DOMAIN

Python beeos_cloud_harness_sdk.jcs · Python only

Domain string beeos.runtime.registration.v1 for registration identity proofs.

REGISTRATION_HASH_DOMAIN = 'beeos.runtime.registration.v1'

BeeOS CloudBack to documentation