clawdentity 0.0.0

package/skill-bundle/openclaw-skill/dist/relay-to-peer.mjs

@@ -0,0 +1,256 @@
+// src/transforms/peers-config.ts
+import { chmod, mkdir, readFile, writeFile } from "fs/promises";
+import { homedir } from "os";
+import { dirname, join } from "path";
+var CLAWDENTITY_DIR = ".clawdentity";
+var PEERS_FILENAME = "peers.json";
+var PEER_ALIAS_PATTERN = /^[a-zA-Z0-9._-]+$/;
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+function getErrorCode(error) {
+  if (!isRecord(error)) {
+    return void 0;
+  }
+  return typeof error.code === "string" ? error.code : void 0;
+}
+function parseNonEmptyString(value, label) {
+  if (typeof value !== "string") {
+    throw new Error(`${label} must be a string`);
+  }
+  const trimmed = value.trim();
+  if (trimmed.length === 0) {
+    throw new Error(`${label} must not be empty`);
+  }
+  return trimmed;
+}
+function parsePeerAlias(value) {
+  const alias = parseNonEmptyString(value, "peer alias");
+  if (alias.length > 128) {
+    throw new Error("peer alias must be at most 128 characters");
+  }
+  if (!PEER_ALIAS_PATTERN.test(alias)) {
+    throw new Error(
+      "peer alias must use only letters, numbers, dot, underscore, or hyphen"
+    );
+  }
+  return alias;
+}
+function parseDid(value) {
+  const did = parseNonEmptyString(value, "did");
+  if (!did.startsWith("did:")) {
+    throw new Error("did must start with 'did:'");
+  }
+  return did;
+}
+function parseProxyUrl(value) {
+  const candidate = parseNonEmptyString(value, "proxyUrl");
+  try {
+    return new URL(candidate).toString();
+  } catch {
+    throw new Error("proxyUrl must be a valid URL");
+  }
+}
+function parsePeerName(value) {
+  if (value === void 0) {
+    return void 0;
+  }
+  return parseNonEmptyString(value, "name");
+}
+function parsePeerEntry(value) {
+  if (!isRecord(value)) {
+    throw new Error("peer entry must be an object");
+  }
+  const did = parseDid(value.did);
+  const proxyUrl = parseProxyUrl(value.proxyUrl);
+  const name = parsePeerName(value.name);
+  if (name === void 0) {
+    return { did, proxyUrl };
+  }
+  return { did, proxyUrl, name };
+}
+function parsePeersConfig(value, source) {
+  if (!isRecord(value)) {
+    throw new Error(
+      `Peer config validation failed at ${source}: root must be an object`
+    );
+  }
+  const peersRaw = value.peers;
+  if (peersRaw === void 0) {
+    return { peers: {} };
+  }
+  if (!isRecord(peersRaw)) {
+    throw new Error(
+      `Peer config validation failed at ${source}: peers must be an object`
+    );
+  }
+  const peers = {};
+  for (const [alias, peerValue] of Object.entries(peersRaw)) {
+    const normalizedAlias = parsePeerAlias(alias);
+    try {
+      peers[normalizedAlias] = parsePeerEntry(peerValue);
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error);
+      throw new Error(
+        `Peer config validation failed at ${source}: peers.${normalizedAlias}: ${reason}`
+      );
+    }
+  }
+  return { peers };
+}
+function resolvePeersConfigPath(options = {}) {
+  if (typeof options.configPath === "string" && options.configPath.trim().length > 0) {
+    return options.configPath.trim();
+  }
+  if (typeof options.configDir === "string" && options.configDir.trim().length > 0) {
+    return join(options.configDir.trim(), PEERS_FILENAME);
+  }
+  const home = typeof options.homeDir === "string" && options.homeDir.trim().length > 0 ? options.homeDir.trim() : homedir();
+  return join(home, CLAWDENTITY_DIR, PEERS_FILENAME);
+}
+async function loadPeersConfig(options = {}) {
+  const configPath = resolvePeersConfigPath(options);
+  let rawJson;
+  try {
+    rawJson = await readFile(configPath, "utf8");
+  } catch (error) {
+    if (getErrorCode(error) === "ENOENT") {
+      return { peers: {} };
+    }
+    throw error;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(rawJson);
+  } catch {
+    throw new Error(`Peer config at ${configPath} is not valid JSON`);
+  }
+  return parsePeersConfig(parsed, configPath);
+}
+
+// src/transforms/relay-to-peer.ts
+var DEFAULT_CONNECTOR_BASE_URL = "http://127.0.0.1:19400";
+var DEFAULT_CONNECTOR_OUTBOUND_PATH = "/v1/outbound";
+function isRecord2(value) {
+  return typeof value === "object" && value !== null;
+}
+function parseRequiredString(value) {
+  if (typeof value !== "string") {
+    throw new Error("Input value must be a string");
+  }
+  const trimmed = value.trim();
+  if (trimmed.length === 0) {
+    throw new Error("Input value must not be empty");
+  }
+  return trimmed;
+}
+function removePeerField(payload) {
+  const outbound = {};
+  for (const [key, value] of Object.entries(payload)) {
+    if (key !== "peer") {
+      outbound[key] = value;
+    }
+  }
+  return outbound;
+}
+function resolveRelayFetch(fetchImpl) {
+  const resolved = fetchImpl ?? globalThis.fetch;
+  if (typeof resolved !== "function") {
+    throw new Error("fetch implementation is required");
+  }
+  return resolved;
+}
+function parseConnectorBaseUrl(value) {
+  let parsed;
+  try {
+    parsed = new URL(value);
+  } catch {
+    throw new Error("Connector base URL is invalid");
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new Error("Connector base URL is invalid");
+  }
+  if (parsed.pathname === "/" && parsed.search.length === 0 && parsed.hash.length === 0) {
+    return parsed.origin;
+  }
+  return parsed.toString();
+}
+function normalizeConnectorPath(value) {
+  const trimmed = value.trim();
+  if (trimmed.length === 0) {
+    throw new Error("Connector outbound path is invalid");
+  }
+  return trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+}
+function resolveConnectorEndpoint(options) {
+  const baseUrlInput = options.connectorBaseUrl ?? process.env.CLAWDENTITY_CONNECTOR_BASE_URL ?? DEFAULT_CONNECTOR_BASE_URL;
+  const pathInput = options.connectorPath ?? process.env.CLAWDENTITY_CONNECTOR_OUTBOUND_PATH ?? DEFAULT_CONNECTOR_OUTBOUND_PATH;
+  const baseUrl = parseConnectorBaseUrl(baseUrlInput.trim());
+  const path = normalizeConnectorPath(pathInput.trim());
+  return new URL(path, baseUrl).toString();
+}
+function mapConnectorFailure(status) {
+  if (status === 404) {
+    return new Error("Local connector outbound endpoint is unavailable");
+  }
+  if (status === 409) {
+    return new Error("Peer alias is not configured");
+  }
+  if (status === 400 || status === 422) {
+    return new Error("Local connector rejected outbound relay payload");
+  }
+  return new Error("Local connector outbound relay request failed");
+}
+async function postToConnector(endpoint, payload, fetchImpl) {
+  let response;
+  try {
+    response = await fetchImpl(endpoint, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify(payload)
+    });
+  } catch {
+    throw new Error("Local connector outbound relay request failed");
+  }
+  if (!response.ok) {
+    throw mapConnectorFailure(response.status);
+  }
+}
+async function relayPayloadToPeer(payload, options = {}) {
+  if (!isRecord2(payload)) {
+    return payload;
+  }
+  const peerAliasValue = payload.peer;
+  if (peerAliasValue === void 0) {
+    return payload;
+  }
+  const peerAlias = parseRequiredString(peerAliasValue);
+  const peersConfig = await loadPeersConfig(options);
+  const peerEntry = peersConfig.peers[peerAlias];
+  if (!peerEntry) {
+    throw new Error("Peer alias is not configured");
+  }
+  const connectorEndpoint = resolveConnectorEndpoint(options);
+  const fetchImpl = resolveRelayFetch(options.fetchImpl);
+  const outboundPayload = removePeerField(payload);
+  await postToConnector(
+    connectorEndpoint,
+    {
+      peer: peerAlias,
+      peerDid: peerEntry.did,
+      peerProxyUrl: peerEntry.proxyUrl,
+      payload: outboundPayload
+    },
+    fetchImpl
+  );
+  return null;
+}
+async function relayToPeer(ctx) {
+  return relayPayloadToPeer(ctx?.payload);
+}
+export {
+  relayToPeer as default,
+  relayPayloadToPeer
+};

package/skill-bundle/openclaw-skill/skill/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: clawdentity_openclaw_relay
+description: This skill should be used when the user asks to "install clawdentity relay skill", "set up agent-to-agent relay from invite code", "connect OpenClaw agents with invite code", or needs OpenClaw peer communication through the local Clawdentity connector runtime.
+version: 0.1.0
+---
+
+# Clawdentity OpenClaw Relay Skill
+
+This skill configures an OpenClaw agent to relay selected webhook payloads to a peer through the local Clawdentity connector runtime using a single invite code.
+
+## Trigger Conditions
+
+Use this skill when any of the following are requested:
+- Install relay support for OpenClaw peer communication.
+- Complete first-time setup from an invite code.
+- Repair broken relay setup after config drift.
+- Verify invite-code onboarding and peer mapping.
+
+## Filesystem Truth (must be used exactly)
+
+### OpenClaw state files
+- OpenClaw state root (default): `~/.openclaw`
+- OpenClaw config: `~/.openclaw/openclaw.json`
+- Transform target path: `~/.openclaw/hooks/transforms/relay-to-peer.mjs`
+- Workspace skill location: `~/.openclaw/workspace/skills/clawdentity-openclaw-relay/SKILL.md`
+- Default transform source expected by CLI setup:
+  `~/.openclaw/workspace/skills/clawdentity-openclaw-relay/relay-to-peer.mjs`
+
+### Clawdentity identity files
+- Clawdentity root: `~/.clawdentity`
+- Agent config: `~/.clawdentity/config.json`
+- Agent identity directory: `~/.clawdentity/agents/<agent-name>/`
+- Agent private key: `~/.clawdentity/agents/<agent-name>/secret.key`
+- Agent AIT token: `~/.clawdentity/agents/<agent-name>/ait.jwt`
+- Peer map: `~/.clawdentity/peers.json`
+- Local selected agent marker: `~/.clawdentity/openclaw-agent-name`
+- Relay runtime config: `~/.clawdentity/openclaw-relay.json`
+
+## Invite Input Assumption
+
+Provide a valid invite code string before running this skill.
+Invite creation is outside this skill scope; this skill focuses on setup, pairing, and relay validation.
+
+## Human + Agent Flow (strict user-style)
+
+Follow this order. Do not skip steps.
+
+## Tool Execution Contract (Agent)
+
+This skill is operational. The agent must execute side effects via tools.
+- Use the `exec` tool for npm/CLI/filesystem actions needed by onboarding.
+- Do not ask the human to run shell commands that the agent can run itself.
+- Ask the human only for missing secrets/inputs (for example API key or invite code).
+- Report final status with concrete outputs (local DID, peer alias, written paths).
+
+## CLI Command Utilization (required)
+
+Use these commands as the default execution path for skill utilization:
+
+- Initialize local CLI config:
+  - `clawdentity config init`
+- Configure registry URL and API key when missing:
+  - `clawdentity config set registryUrl <registry-url>`
+  - `clawdentity config set apiKey <api-key>`
+- Create and inspect local OpenClaw agent identity:
+  - `clawdentity agent create <agent-name> --framework openclaw`
+  - `clawdentity agent inspect <agent-name>`
+- Apply OpenClaw invite setup:
+  - `clawdentity openclaw setup <agent-name> --invite-code <invite-code>`
+- Start connector runtime for relay handoff:
+  - `clawdentity connector start <agent-name>`
+- Optional persistent connector autostart:
+  - `clawdentity connector service install <agent-name>`
+- Validate health and delivery:
+  - `clawdentity openclaw doctor`
+  - `clawdentity openclaw relay test --peer <alias>`
+
+Pairing bootstrap for trust policy is API-based in the current release (no dedicated pairing CLI command yet):
+
+- Owner/initiator starts pairing on initiator proxy:
+  - `POST /pair/start`
+  - Requires `Authorization: Claw <AIT>` and `x-claw-owner-pat`
+  - Body: `{"agentDid":"<responder-agent-did>"}`
+- Responder confirms on responder proxy:
+  - `POST /pair/confirm`
+  - Requires `Authorization: Claw <AIT>`
+  - Body: `{"pairingCode":"<code-from-start>"}`
+
+Successful confirm establishes mutual trust for the two agent DIDs. After confirm, both directions are allowed for trusted delivery.
+
+1. Confirm prerequisites with the human.
+- Confirm `clawdentity` CLI is installed and runnable.
+- Confirm API key exists for this agent (if missing, ask the human for it).
+- Confirm OpenClaw state directory path if non-default.
+- Confirm OpenClaw base URL if local endpoint is non-default.
+
+2. Confirm skill artifact exists in workspace skills directory.
+- Ensure `~/.openclaw/workspace/skills/clawdentity-openclaw-relay/relay-to-peer.mjs` exists.
+- If missing, install/update skill package contents before setup.
+
+3. Configure local Clawdentity identity for this OpenClaw agent.
+- Run `clawdentity config init`.
+- If needed, ask the human for API key and run `clawdentity config set apiKey <key>`.
+- Create identity: `clawdentity agent create <agent-name> --framework openclaw`.
+- Verify identity: `clawdentity agent inspect <agent-name>`.
+
+4. Ask the human for invite code.
+- Prompt exactly for one invite code string.
+- Do not ask for DID/proxy URL when invite code is present.
+
+5. Run automated setup from invite code.
+- Execute:
+  `clawdentity openclaw setup <agent-name> --invite-code <invite-code>`
+- Use `--openclaw-dir <path>` when state directory is non-default.
+- Use `--openclaw-base-url <url>` when local OpenClaw HTTP endpoint is non-default.
+- Use `--peer-alias <alias>` only when alias override is required.
+
+6. Verify setup outputs.
+- Confirm setup reports:
+  - peer alias
+  - peer DID
+  - updated OpenClaw config path
+  - installed transform path
+  - OpenClaw base URL
+  - relay runtime config path
+- Confirm `~/.clawdentity/openclaw-agent-name` is set to the local agent name.
+
+7. Start connector runtime for local relay handoff.
+- Run `clawdentity connector start <agent-name>`.
+- Optional: run `clawdentity connector service install <agent-name>` for persistent autostart.
+
+8. Complete trust pairing bootstrap.
+- Run pairing start (`POST /pair/start`) from the owner/initiator side.
+- Share returned one-time `pairingCode` with responder side.
+- Run pairing confirm (`POST /pair/confirm`) from responder side.
+- Confirm pairing success before relay test.
+
+9. Validate with user-style relay test.
+- Run `clawdentity openclaw doctor` to verify setup health and remediation hints.
+- Run `clawdentity openclaw relay test --peer <alias>` to execute a probe.
+- Confirm probe success and connector-mediated delivery logs.
+- Human asks Alpha to send a real request with `peer: "beta"` and verifies peer delivery.
+
+## Required question policy
+
+Ask the human only when required inputs are missing:
+- Missing Clawdentity API key.
+- Unclear OpenClaw state directory.
+- Non-default OpenClaw base URL.
+- Missing invite code.
+- Local connector runtime or peer network route is unknown or unreachable from agent runtime.
+
+## Failure Handling
+
+If setup or relay fails:
+- Report precise missing file/path/value.
+- Fix only the failing config/input.
+- Ensure connector runtime is active (`clawdentity connector start <agent-name>`).
+- Re-run `clawdentity openclaw doctor`.
+- Re-run `clawdentity openclaw relay test --peer <alias>`.
+- Re-run the same user-style flow from step 5 onward only after health checks pass.
+
+## Bundled Resources
+
+### References
+| File | Purpose |
+|------|---------|
+| `references/clawdentity-protocol.md` | Invite format, peer map schema, connector handoff envelope, and runtime failure mapping |
+
+Directive: read the reference file before troubleshooting relay contract or connector handoff failures.

package/skill-bundle/openclaw-skill/skill/references/clawdentity-protocol.md

@@ -0,0 +1,175 @@
+# Clawdentity Relay Protocol Reference
+
+## Purpose
+
+Define the exact runtime contract used by `relay-to-peer.mjs`.
+
+## Filesystem Paths
+
+### OpenClaw files
+- `~/.openclaw/openclaw.json`
+- `~/.openclaw/hooks/transforms/relay-to-peer.mjs`
+- `~/.openclaw/workspace/skills/clawdentity-openclaw-relay/SKILL.md`
+
+### Clawdentity files
+- `~/.clawdentity/config.json`
+- `~/.clawdentity/agents/<agent-name>/secret.key`
+- `~/.clawdentity/agents/<agent-name>/ait.jwt`
+- `~/.clawdentity/peers.json`
+- `~/.clawdentity/openclaw-agent-name`
+- `~/.clawdentity/openclaw-relay.json`
+
+## Invite Code Contract
+
+Invite codes are prefixed with `clawd1_` and contain base64url JSON:
+
+```json
+{
+  "v": 1,
+  "issuedAt": "2026-02-15T20:00:00.000Z",
+  "did": "did:claw:agent:01H...",
+  "proxyUrl": "https://beta-proxy.example.com/hooks/agent",
+  "alias": "beta",
+  "name": "Beta Agent"
+}
+```
+
+Rules:
+- `v` must be `1`.
+- `issuedAt` is ISO-8601 UTC timestamp.
+- `did` must be an agent DID.
+- `proxyUrl` must be absolute `http` or `https`.
+- `alias` is optional but preferred for zero-question setup.
+
+## Peer Map Schema
+
+`~/.clawdentity/peers.json` must be valid JSON:
+
+```json
+{
+  "peers": {
+    "beta": {
+      "did": "did:claw:agent:01H...",
+      "proxyUrl": "https://beta-proxy.example.com/hooks/agent",
+      "name": "Beta Agent"
+    }
+  }
+}
+```
+
+Rules:
+- peer alias key uses `[a-zA-Z0-9._-]`
+- `did` required and must begin with `did:`
+- `proxyUrl` required and must be a valid absolute URL
+- `name` optional
+
+## Proxy Pairing Prerequisite
+
+Relay delivery policy is trust-pair based on proxy side. Pairing must be completed before first cross-agent delivery.
+
+Current pairing contract is API-based (no dedicated CLI pairing command):
+
+1. Initiator owner starts pairing:
+   - `POST /pair/start`
+   - headers:
+     - `Authorization: Claw <AIT>`
+     - `x-claw-owner-pat: <owner-pat>`
+   - body:
+
+```json
+{
+  "agentDid": "did:claw:agent:01RESPONDER..."
+}
+```
+
+2. Responder confirms pairing:
+   - `POST /pair/confirm`
+   - headers:
+     - `Authorization: Claw <AIT>`
+   - body:
+
+```json
+{
+  "pairingCode": "01PAIRCODE..."
+}
+```
+
+Rules:
+- `pairingCode` is one-time and expires.
+- Confirm establishes mutual trust for the initiator/responder pair.
+- Same-agent sender/recipient is allowed by policy without explicit pair entry.
+
+## Relay Input Contract
+
+The OpenClaw transform reads `ctx.payload`.
+
+- If `payload.peer` is absent:
+  - return payload unchanged
+  - do not relay
+- If `payload.peer` exists:
+  - resolve peer from `peers.json`
+  - remove `peer` from forwarded body
+  - send JSON POST to local connector outbound endpoint
+  - return `null` to skip local handling
+
+## Relay Agent Selection Contract
+
+Relay resolves local agent name in this order:
+1. transform option `agentName`
+2. `CLAWDENTITY_AGENT_NAME`
+3. `~/.clawdentity/openclaw-agent-name`
+4. single local agent fallback from `~/.clawdentity/agents/`
+
+## Local OpenClaw Base URL Contract
+
+`~/.clawdentity/openclaw-relay.json` stores the OpenClaw upstream base URL used by local proxy runtime fallback:
+
+```json
+{
+  "openclawBaseUrl": "http://127.0.0.1:18789",
+  "updatedAt": "2026-02-15T20:00:00.000Z"
+}
+```
+
+Rules:
+- `openclawBaseUrl` must be absolute `http` or `https`.
+- `updatedAt` is ISO-8601 UTC timestamp.
+- Proxy runtime precedence is: `OPENCLAW_BASE_URL` env first, then `openclaw-relay.json`, then built-in default.
+
+## Connector Handoff Contract
+
+The transform does not send directly to the peer proxy. It posts to the local connector runtime:
+- Default endpoint: `http://127.0.0.1:19400/v1/outbound`
+- Optional overrides:
+  - `CLAWDENTITY_CONNECTOR_BASE_URL`
+  - `CLAWDENTITY_CONNECTOR_OUTBOUND_PATH`
+
+Outbound JSON body sent by transform:
+
+```json
+{
+  "peer": "beta",
+  "peerDid": "did:claw:agent:01H...",
+  "peerProxyUrl": "https://beta-proxy.example.com/hooks/agent",
+  "payload": {
+    "event": "agent.message"
+  }
+}
+```
+
+Rules:
+- `payload.peer` is removed before creating the `payload` object above.
+- Transform sends `Content-Type: application/json` only.
+- Connector runtime is responsible for Clawdentity auth headers and request signing when calling peer proxy.
+
+## Error Conditions
+
+Relay fails when:
+- no selected local agent can be resolved
+- peer alias missing from config
+- local connector outbound endpoint is unavailable (`404`)
+- local connector reports unknown peer alias (`409`)
+- local connector rejects payload (`400` or `422`)
+- local connector outbound request fails (network/other non-2xx)
+
+Error messages should include file/path context but never print secret content.