@clanker-chain/identity-plugin 0.0.1

package/dist/index.js

@@ -0,0 +1,12 @@
+import { emptyPluginConfigSchema } from "openclaw/plugin-sdk/core";
+const plugin = {
+    id: "clanker-chain-identity",
+    name: "Clanker Chain Identity",
+    description: "Identity client and identity skill for clanker-chain bots.",
+    configSchema: emptyPluginConfigSchema(),
+    register(_api) {
+        // No channels or HTTP routes yet; the primary value is the identity skill
+        // shipped via `skills` in openclaw.plugin.json.
+    },
+};
+export default plugin;

package/dist/src/client.js

@@ -0,0 +1,165 @@
+import { promises as fs } from "fs";
+import path from "path";
+import os from "os";
+import * as ed25519 from "@noble/ed25519";
+import { SignJWT, importJWK } from "jose";
+const MQTT_TOKEN_AUD = "clanker-mqtt";
+function base64url(buf) {
+    return Buffer.from(buf)
+        .toString("base64")
+        .replace(/\+/g, "-")
+        .replace(/\//g, "_")
+        .replace(/=+$/, "");
+}
+export class IdentityClient {
+    constructor(options) {
+        this.botId = options.botId;
+        this.operatorId = options.operatorId;
+        this.baseUrl = options.identityServiceUrl ?? process.env.IDENTITY_SERVICE_URL ?? "http://localhost:8080";
+        const defaultKeyPath = path.join(os.homedir(), ".openclaw", "keys", `${this.botId}.key`);
+        this.keyPath = options.keyPath ?? defaultKeyPath;
+    }
+    /**
+     * Ensure a private key exists on disk, returning the 32-byte private key.
+     */
+    async loadOrCreatePrivateKey() {
+        try {
+            const raw = await fs.readFile(this.keyPath, "utf8");
+            const bytes = Buffer.from(raw.trim(), "base64");
+            if (bytes.length !== 32) {
+                throw new Error("invalid key length");
+            }
+            return new Uint8Array(bytes);
+        }
+        catch {
+            await fs.mkdir(path.dirname(this.keyPath), { recursive: true });
+            const priv = ed25519.utils.randomPrivateKey();
+            const b64 = Buffer.from(priv).toString("base64");
+            await fs.writeFile(this.keyPath, `${b64}\n`, { encoding: "utf8", mode: 0o600 });
+            return priv;
+        }
+    }
+    /**
+     * Derive the base64-encoded public key from the local private key.
+     */
+    async getPublicKeyBase64() {
+        const priv = await this.loadOrCreatePrivateKey();
+        const pub = await ed25519.getPublicKeyAsync(priv);
+        return Buffer.from(pub).toString("base64");
+    }
+    async getJson(pathName) {
+        const url = new URL(pathName, this.baseUrl).toString();
+        const res = await fetch(url, { method: "GET" });
+        const text = await res.text();
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            throw new Error(`Unexpected response from identity service: ${text}`);
+        }
+        if (!res.ok) {
+            const err = parsed;
+            throw new Error(err.message || err.error || `HTTP ${res.status}`);
+        }
+        return parsed;
+    }
+    /**
+     * Verify that the operator and bot exist in the identity service and that
+     * this instance's public key is registered on the bot. Does not create
+     * operator or bot; they must be minted by the operator first.
+     * Safe to call multiple times.
+     */
+    async init() {
+        try {
+            await this.getJson(`/v1/operators/${encodeURIComponent(this.operatorId)}`);
+        }
+        catch {
+            throw new Error("Operator not registered. Operator must be minted first (genesis or mint-operator).");
+        }
+        let bot;
+        try {
+            bot = await this.getJson(`/v1/bots/${encodeURIComponent(this.botId)}`);
+        }
+        catch {
+            throw new Error("Bot not registered or key not found; operator must mint this bot with your public key.");
+        }
+        const publicKey = await this.getPublicKeyBase64();
+        const hasKey = bot.public_keys?.some((k) => k.public_key === publicKey && k.status === "active") ?? false;
+        if (!hasKey) {
+            throw new Error("Bot not registered or key not found; operator must mint this bot with your public key.");
+        }
+    }
+    async getBot() {
+        return this.getJson(`/v1/bots/${encodeURIComponent(this.botId)}`);
+    }
+    /**
+     * Canonical JSON serialization used for signing, following bot-comms.md.
+     */
+    static canonicalizeForSignature(msg) {
+        const canonicalFields = {
+            body: msg.body,
+            correlation_id: msg.correlation_id,
+            from: msg.from,
+            from_id: msg.from_id,
+            message_id: msg.message_id,
+            operator_id: msg.operator_id,
+            subtype: msg.subtype,
+            timestamp: msg.timestamp,
+            to: msg.to,
+            to_id: msg.to_id,
+            type: msg.type,
+        };
+        for (const key of Object.keys(canonicalFields)) {
+            if (canonicalFields[key] === undefined || canonicalFields[key] === null) {
+                // eslint-disable-next-line @typescript-eslint/no-dynamic-delete
+                // Dynamic delete is intentional to keep the canonical JSON minimal.
+                // @ts-ignore dynamic delete
+                delete canonicalFields[key];
+            }
+        }
+        const sortedKeys = Object.keys(canonicalFields).sort();
+        return JSON.stringify(canonicalFields, sortedKeys);
+    }
+    /**
+     * Sign a message envelope using the local Ed25519 private key.
+     * Returns base64(signature) and signature_scheme.
+     */
+    async signMessage(msg) {
+        const priv = await this.loadOrCreatePrivateKey();
+        const canonical = IdentityClient.canonicalizeForSignature(msg);
+        const bytes = new TextEncoder().encode(canonical);
+        const sig = await ed25519.signAsync(bytes, priv);
+        return {
+            signature: Buffer.from(sig).toString("base64"),
+            signature_scheme: "ed25519",
+        };
+    }
+    /**
+     * Issue a short-lived JWT for MQTT broker authentication (EdDSA / Ed25519).
+     * Use as the MQTT CONNECT password with username = bot_id.
+     */
+    async issueMqttToken(ttlSec = 300) {
+        const priv = await this.loadOrCreatePrivateKey();
+        const pub = await ed25519.getPublicKeyAsync(priv);
+        const jwk = {
+            kty: "OKP",
+            crv: "Ed25519",
+            d: base64url(priv),
+            x: base64url(pub),
+        };
+        const key = await importJWK(jwk, "EdDSA");
+        if (!key) {
+            throw new Error("Failed to import key for MQTT token");
+        }
+        const exp = Math.floor(Date.now() / 1000) + ttlSec;
+        const jwt = await new SignJWT({})
+            .setProtectedHeader({ alg: "EdDSA", typ: "JWT" })
+            .setSubject(this.botId)
+            .setAudience(MQTT_TOKEN_AUD)
+            .setExpirationTime(exp)
+            .sign(key);
+        return jwt;
+    }
+}
+export * from "./types";

package/dist/src/types.js

@@ -0,0 +1 @@
+export {};

package/index.ts

@@ -0,0 +1,15 @@
+import type { OpenClawCorePluginApi } from "openclaw/plugin-sdk/core";
+import { emptyPluginConfigSchema } from "openclaw/plugin-sdk/core";
+
+const plugin = {
+  id: "clanker-chain-identity",
+  name: "Clanker Chain Identity",
+  description: "Identity client and identity skill for clanker-chain bots.",
+  configSchema: emptyPluginConfigSchema(),
+  register(_api: OpenClawCorePluginApi) {
+    // No channels or HTTP routes yet; the primary value is the identity skill
+    // shipped via `skills` in openclaw.plugin.json.
+  },
+};
+
+export default plugin;

package/install.sh

@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+PLUGIN_NAME="clanker-chain-identity"
+if [ -n "${OPENCLAW_EXTENSIONS_DIR:-}" ]; then
+  TARGET_ROOT="$OPENCLAW_EXTENSIONS_DIR"
+  # OpenClaw Docker: app loads from /app/extensions; /extensions would be wrong
+  if [ "$TARGET_ROOT" = /extensions ] && [ -d /app/extensions ]; then
+    TARGET_ROOT="/app/extensions"
+  fi
+elif [ -d /app/extensions ]; then
+  TARGET_ROOT="/app/extensions"
+else
+  TARGET_ROOT="$HOME/.openclaw/extensions"
+fi
+
+echo "Installing $PLUGIN_NAME into: $TARGET_ROOT/$PLUGIN_NAME"
+
+SRC_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+mkdir -p "$TARGET_ROOT"
+rm -rf "$TARGET_ROOT/$PLUGIN_NAME"
+cp -R "$SRC_DIR" "$TARGET_ROOT/$PLUGIN_NAME"
+
+if [ -f "$TARGET_ROOT/$PLUGIN_NAME/package.json" ]; then
+  echo "Running npm install --production inside $TARGET_ROOT/$PLUGIN_NAME (if Node is available)..."
+  (cd "$TARGET_ROOT/$PLUGIN_NAME" && npm install --production) || echo "npm install failed or Node not available; ensure dependencies are installed if required."
+fi
+
+# Expose the plugin's skill as skills/identity so OpenClaw has both the tooling (plugin) and the
+# reference instruction set (SKILL.md in skills/identity), same pattern as Slack.
+SKILLS_DIR="${OPENCLAW_SKILLS_DIR:-}"
+if [ -z "$SKILLS_DIR" ] && [ -d /app/skills ]; then
+  SKILLS_DIR="/app/skills"
+fi
+if [ -n "$SKILLS_DIR" ] && [ -d "$TARGET_ROOT/$PLUGIN_NAME/skill" ]; then
+  rm -rf "$SKILLS_DIR/identity"
+  ln -sf "$TARGET_ROOT/$PLUGIN_NAME/skill" "$SKILLS_DIR/identity"
+  echo "Skill symlink: $SKILLS_DIR/identity -> $TARGET_ROOT/$PLUGIN_NAME/skill"
+fi
+
+# Update OpenClaw workspace lockfile so "docker compose build" with OPENCLAW_EXTENSIONS succeeds
+OPENCLAW_ROOT="${OPENCLAW_ROOT:-$(dirname "$TARGET_ROOT")}"
+if [ -f "$OPENCLAW_ROOT/pnpm-workspace.yaml" ]; then
+  echo "Running pnpm install in OpenClaw repo ($OPENCLAW_ROOT) to update lockfile..."
+  (cd "$OPENCLAW_ROOT" && npx --yes pnpm install --ignore-scripts) || echo "pnpm install skipped (npx/pnpm not available)."
+fi
+
+echo "Done. Restart OpenClaw so it picks up the new plugin."
+echo "Plugin path: $TARGET_ROOT/$PLUGIN_NAME"

package/openclaw.plugin.json

@@ -0,0 +1,13 @@
+{
+  "id": "clanker-chain-identity",
+  "name": "Clanker Chain Identity",
+  "description": "Identity client and identity skill for clanker-chain bots.",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  },
+  "skills": [
+    "src/skill"
+  ]
+}

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@clanker-chain/identity-plugin",
+  "version": "0.0.1",
+  "description": "Identity client and identity skill for clanker-chain bots.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "openclaw": {
+    "extensions": ["./dist/index.js"]
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  },
+  "dependencies": {
+    "@noble/ed25519": "^2.3.0",
+    "jose": "^5.9.6",
+    "typescript": "^5.9.3"
+  },
+  "devDependencies": {
+    "@types/node": "^25.4.0"
+  }
+}

package/src/client.ts

@@ -0,0 +1,211 @@
+import { promises as fs } from "fs";
+import path from "path";
+import os from "os";
+import * as ed25519 from "@noble/ed25519";
+import { SignJWT, importJWK } from "jose";
+import type { BotRecord, IdentityMessageEnvelope, OperatorRecord, PublicKeyRecord } from "./types";
+
+const MQTT_TOKEN_AUD = "clanker-mqtt";
+
+function base64url(buf: Uint8Array): string {
+  return Buffer.from(buf)
+    .toString("base64")
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=+$/, "");
+}
+
+export interface IdentityClientOptions {
+  botId: string;
+  operatorId: string;
+  /**
+   * Base URL of the identity service, e.g. "http://localhost:8080".
+   * Defaults to process.env.IDENTITY_SERVICE_URL or http://localhost:8080.
+   */
+  identityServiceUrl?: string;
+  /**
+   * Path to the private key file. Defaults to ~/.openclaw/keys/{botId}.key
+   */
+  keyPath?: string;
+}
+
+export class IdentityClient {
+  private readonly botId: string;
+  private readonly operatorId: string;
+  private readonly baseUrl: string;
+  private readonly keyPath: string;
+
+  constructor(options: IdentityClientOptions) {
+    this.botId = options.botId;
+    this.operatorId = options.operatorId;
+    this.baseUrl = options.identityServiceUrl ?? process.env.IDENTITY_SERVICE_URL ?? "http://localhost:8080";
+    const defaultKeyPath = path.join(os.homedir(), ".openclaw", "keys", `${this.botId}.key`);
+    this.keyPath = options.keyPath ?? defaultKeyPath;
+  }
+
+  /**
+   * Ensure a private key exists on disk, returning the 32-byte private key.
+   */
+  private async loadOrCreatePrivateKey(): Promise<Uint8Array> {
+    try {
+      const raw = await fs.readFile(this.keyPath, "utf8");
+      const bytes = Buffer.from(raw.trim(), "base64");
+      if (bytes.length !== 32) {
+        throw new Error("invalid key length");
+      }
+      return new Uint8Array(bytes);
+    } catch {
+      await fs.mkdir(path.dirname(this.keyPath), { recursive: true });
+      const priv = ed25519.utils.randomPrivateKey();
+      const b64 = Buffer.from(priv).toString("base64");
+      await fs.writeFile(this.keyPath, `${b64}\n`, { encoding: "utf8", mode: 0o600 });
+      return priv;
+    }
+  }
+
+  /**
+   * Derive the base64-encoded public key from the local private key.
+   */
+  async getPublicKeyBase64(): Promise<string> {
+    const priv = await this.loadOrCreatePrivateKey();
+    const pub = await ed25519.getPublicKeyAsync(priv);
+    return Buffer.from(pub).toString("base64");
+  }
+
+  private async getJson<T>(pathName: string): Promise<T> {
+    const url = new URL(pathName, this.baseUrl).toString();
+    const res = await fetch(url, { method: "GET" });
+    const text = await res.text();
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      throw new Error(`Unexpected response from identity service: ${text}`);
+    }
+    if (!res.ok) {
+      const err = parsed as { error?: string; message?: string };
+      throw new Error(err.message || err.error || `HTTP ${res.status}`);
+    }
+    return parsed as T;
+  }
+
+  /**
+   * Verify that the operator and bot exist in the identity service and that
+   * this instance's public key is registered on the bot. Does not create
+   * operator or bot; they must be minted by the operator first.
+   * Safe to call multiple times.
+   */
+  async init(): Promise<void> {
+    try {
+      await this.getJson<OperatorRecord>(
+        `/v1/operators/${encodeURIComponent(this.operatorId)}`,
+      );
+    } catch {
+      throw new Error(
+        "Operator not registered. Operator must be minted first (genesis or mint-operator).",
+      );
+    }
+
+    let bot: BotRecord;
+    try {
+      bot = await this.getJson<BotRecord>(
+        `/v1/bots/${encodeURIComponent(this.botId)}`,
+      );
+    } catch {
+      throw new Error(
+        "Bot not registered or key not found; operator must mint this bot with your public key.",
+      );
+    }
+
+    const publicKey = await this.getPublicKeyBase64();
+    const hasKey =
+      bot.public_keys?.some(
+        (k) => k.public_key === publicKey && k.status === "active",
+      ) ?? false;
+    if (!hasKey) {
+      throw new Error(
+        "Bot not registered or key not found; operator must mint this bot with your public key.",
+      );
+    }
+  }
+
+  async getBot(): Promise<BotRecord> {
+    return this.getJson<BotRecord>(`/v1/bots/${encodeURIComponent(this.botId)}`);
+  }
+
+  /**
+   * Canonical JSON serialization used for signing, following bot-comms.md.
+   */
+  private static canonicalizeForSignature(msg: IdentityMessageEnvelope): string {
+    const canonicalFields: Record<string, unknown> = {
+      body: msg.body,
+      correlation_id: msg.correlation_id,
+      from: msg.from,
+      from_id: msg.from_id,
+      message_id: msg.message_id,
+      operator_id: msg.operator_id,
+      subtype: msg.subtype,
+      timestamp: msg.timestamp,
+      to: msg.to,
+      to_id: msg.to_id,
+      type: msg.type,
+    };
+    for (const key of Object.keys(canonicalFields)) {
+      if (canonicalFields[key] === undefined || canonicalFields[key] === null) {
+        // eslint-disable-next-line @typescript-eslint/no-dynamic-delete
+        // Dynamic delete is intentional to keep the canonical JSON minimal.
+        // @ts-ignore dynamic delete
+        delete (canonicalFields as Record<string, unknown>)[key];
+      }
+    }
+    const sortedKeys = Object.keys(canonicalFields).sort();
+    return JSON.stringify(canonicalFields, sortedKeys as (keyof typeof canonicalFields)[]);
+  }
+
+  /**
+   * Sign a message envelope using the local Ed25519 private key.
+   * Returns base64(signature) and signature_scheme.
+   */
+  async signMessage(msg: IdentityMessageEnvelope): Promise<{
+    signature: string;
+    signature_scheme: "ed25519";
+  }> {
+    const priv = await this.loadOrCreatePrivateKey();
+    const canonical = IdentityClient.canonicalizeForSignature(msg);
+    const bytes = new TextEncoder().encode(canonical);
+    const sig = await ed25519.signAsync(bytes, priv);
+    return {
+      signature: Buffer.from(sig).toString("base64"),
+      signature_scheme: "ed25519",
+    };
+  }
+
+  /**
+   * Issue a short-lived JWT for MQTT broker authentication (EdDSA / Ed25519).
+   * Use as the MQTT CONNECT password with username = bot_id.
+   */
+  async issueMqttToken(ttlSec: number = 300): Promise<string> {
+    const priv = await this.loadOrCreatePrivateKey();
+    const pub = await ed25519.getPublicKeyAsync(priv);
+    const jwk = {
+      kty: "OKP" as const,
+      crv: "Ed25519" as const,
+      d: base64url(priv),
+      x: base64url(pub),
+    };
+    const key = await importJWK(jwk, "EdDSA");
+    if (!key) {
+      throw new Error("Failed to import key for MQTT token");
+    }
+    const exp = Math.floor(Date.now() / 1000) + ttlSec;
+    const jwt = await new SignJWT({})
+      .setProtectedHeader({ alg: "EdDSA", typ: "JWT" })
+      .setSubject(this.botId)
+      .setAudience(MQTT_TOKEN_AUD)
+      .setExpirationTime(exp)
+      .sign(key);
+    return jwt;
+  }
+}
+
+export * from "./types";

package/src/openclaw-plugin-sdk-core.d.ts

@@ -0,0 +1,15 @@
+declare module "openclaw/plugin-sdk/core" {
+  // This package is built and typechecked outside an OpenClaw checkout.
+  // At runtime, OpenClaw provides the real module.
+  //
+  // We only need minimal declarations for CI/local TypeScript compilation
+  // so bundling can succeed even when `openclaw` isn't installed here.
+  export type OpenClawCorePluginApi = unknown;
+
+  export function emptyPluginConfigSchema(): {
+    type: "object";
+    additionalProperties: false;
+    properties: {};
+  };
+}
+

package/src/skill/SKILL.md

@@ -0,0 +1,284 @@
+---
+name: identity
+description: Register this bot with the identity service, fetch bot records, and sign coordination messages (Ed25519) for the bot mesh.
+metadata:
+  {"openclaw":{"requires":{"env":["IDENTITY_SERVICE_URL"]},"primaryEnv":"IDENTITY_SERVICE_URL"}}
+---
+
+# Identity skill
+
+Use this skill when:
+
+- **Bootstrapping or restarting a bot**: verify that the operator and bot exist in the identity service and that this bot’s public key is registered, so other bots can verify its signatures.
+- **Sending a signed message** to another bot over MQTT (or any channel): produce a signed envelope so the recipient can verify authenticity.
+- **Looking up a bot’s record** (e.g. public keys, operator, status) for debugging or coordination.
+
+This skill is a thin wrapper around the `identity-node-client` library and expects the underlying clanker-chain identity service to use **proof-based authorization** (Ed25519 signatures). No Bearer admin token is required in the default setup.
+
+---
+
+## Configuration
+
+At minimum, you must configure:
+
+- **Identity service URL**:
+  - Env: `IDENTITY_SERVICE_URL`
+  - Example: `http://localhost:8080` or `http://identity-service:8080`
+- **Bot identity**:
+  - `bot_id`: canonical bot id, for example: `openclaw.france.prod-1`
+  - Local private key path: `~/.openclaw/keys/{bot_id}.key`
+- **Operator identity**:
+  - `operator_id`: operator that owns the bot, for example: `org.openclaw.pat`
+
+The default key path is derived from `bot_id`:
+
+- `~/.openclaw/keys/{bot_id}.key` (e.g. `~/.openclaw/keys/openclaw.france.prod-1.key`)
+
+The **mint / registration step is performed by the operator**, not by this skill:
+
+1. The operator uses the identity-service CLI to generate a **mint-bot token**:
+
+   ```bash
+   cd identity-service
+   bun run src/cli.ts mint-bot-token openclaw.france.prod-1 org.openclaw.pat "France Bot"
+   ```
+
+2. The CLI:
+   - Ensures the operator key exists (and creates it if missing).
+   - Generates a new bot keypair and writes the private key to `~/.openclaw/keys/openclaw.france.prod-1.key`.
+   - Prints a JSON payload that can be POSTed directly to `POST /v1/bots` on the identity service.
+
+3. The operator (or deployment pipeline) POSTs that payload once:
+
+   ```bash
+   curl -X POST "$IDENTITY_SERVICE_URL/v1/bots" \
+     -H "content-type: application/json" \
+     -d '@mint-bot-payload.json'
+   ```
+
+4. The private key file is then securely copied to the bot host and kept at `~/.openclaw/keys/openclaw.france.prod-1.key` (mode `0600`).
+
+After this one-time registration, the **bot** uses this skill to verify its identity and sign messages; it does not perform registration itself.
+
+---
+
+## Commands
+
+Run these from the workspace root. Replace `{baseDir}` with the path to this skill folder (e.g. `skills/identity`).
+
+### identity_init — verify bot and key
+
+Call once per bot at startup (idempotent). Ensures:
+
+- The operator exists in the identity service.
+- The bot exists in the identity service.
+- This bot’s local Ed25519 public key (derived from `~/.openclaw/keys/{bot_id}.key`) is present and active in the bot record.
+
+```bash
+node {baseDir}/run.mjs init <bot_id> <operator_id>
+```
+
+Example (canonical pairing from this repo):
+
+```bash
+node skills/identity/run.mjs init openclaw.france.prod-1 org.openclaw.pat
+```
+
+- **bot_id**: Canonical bot ID (e.g. `openclaw.france.prod-1`).
+- **operator_id**: Operator that owns the bot (e.g. `org.openclaw.pat`).
+
+Requires `IDENTITY_SERVICE_URL`. The default identity service in this repo does **not** use `IDENTITY_ADMIN_TOKEN`; all writes are authorized by Ed25519 signatures.
+
+On **success**, `identity_init` prints JSON to stdout:
+
+```json
+{
+  "ok": true,
+  "bot_id": "openclaw.france.prod-1",
+  "operator_id": "org.openclaw.pat",
+  "identity_service_url": "http://localhost:8080",
+  "public_key": "<base64-bot-public-key>",
+  "bot_has_active_key": true,
+  "bot": {
+    "bot_id": "openclaw.france.prod-1",
+    "operator_id": "org.openclaw.pat",
+    "public_keys": [
+      {
+        "key_id": "...",
+        "algorithm": "ed25519",
+        "public_key": "<base64-bot-public-key>",
+        "created": "...",
+        "status": "active"
+      }
+    ],
+    "status": "active",
+    "created": "...",
+    "updated": "..."
+  }
+}
+```
+
+On **failure**, it writes a JSON error to stderr and exits with a non‑zero code:
+
+```json
+{ "error": "Operator not registered. Operator must be minted first (genesis or mint-operator)." }
+```
+
+### identity_get_bot — fetch bot record
+
+Returns the full bot record from the identity service (public keys, operator_id, status).
+
+```bash
+node {baseDir}/run.mjs get-bot <bot_id>
+```
+
+Example:
+
+```bash
+node skills/identity/run.mjs get-bot openclaw.tooter.prod-1
+```
+
+### identity_sign — sign a message envelope
+
+Signs a JSON message envelope with this bot’s Ed25519 key. Use the returned `envelope` (with `signature` and `signature_scheme`) when publishing to MQTT or other channels.
+
+```bash
+node {baseDir}/run.mjs sign '<envelope_json>'
+```
+
+The envelope must include at least: `from`, `from_id`, `operator_id`, `type`, `timestamp`, `message_id`, `body`. Optional: `to`, `to_id`, `subtype`, `channel`, `correlation_id`.
+
+Example (escape the JSON for the shell):
+
+```bash
+node skills/identity/run.mjs sign '{"from":"france-bot","from_id":"openclaw.france.prod-1","operator_id":"org.openclaw.pat","to":"tooter-bot","to_id":"openclaw.tooter.prod-1","type":"coordination","timestamp":"2026-03-09T12:00:00Z","message_id":"msg-1","body":{"action":"ping"}}'
+```
+
+Output is JSON with `signature`, `signature_scheme`, and `envelope` (the full signed envelope to publish).
+
+### identity_verify — detailed registration check
+
+Runs a non‑throwing health check against the identity service for a given bot/operator pair.
+
+```bash
+node {baseDir}/run.mjs verify <bot_id> <operator_id>
+```
+
+Example:
+
+```bash
+node skills/identity/run.mjs verify openclaw.france.prod-1 org.openclaw.pat
+```
+
+On **success**, it prints a summary JSON object and exits with code 0:
+
+```json
+{
+  "ok": true,
+  "bot_id": "openclaw.france.prod-1",
+  "operator_id": "org.openclaw.pat",
+  "identity_service_url": "http://localhost:8080",
+  "operator": { "exists": true },
+  "bot": { "exists": true },
+  "key": {
+    "matches": true,
+    "public_key": "<base64-bot-public-key>"
+  },
+  "error": null
+}
+```
+
+If something is wrong (operator missing, bot missing, or key mismatch), it still exits with code 0 but sets `ok: false` and populates `error`:
+
+```json
+{
+  "ok": false,
+  "bot_id": "openclaw.france.prod-1",
+  "operator_id": "org.openclaw.pat",
+  "identity_service_url": "http://localhost:8080",
+  "operator": { "exists": true },
+  "bot": { "exists": true },
+  "key": {
+    "matches": false,
+    "public_key": "<base64-bot-public-key>"
+  },
+  "error": "bot exists but does not have an active public key matching the local key"
+}
+```
+
+This makes `identity_verify` a good choice for periodic health checks or diagnostics, while `identity_init` is best for strict startup gating.
+
+### identity_issue_mqtt_token — issue MQTT broker auth token
+
+Issues a short-lived JWT signed with this bot’s Ed25519 key for MQTT broker authentication. Use the output as the MQTT CONNECT password with username = `bot_id`.
+
+```bash
+node {baseDir}/run.mjs issue-mqtt-token <bot_id> <operator_id> [ttl_sec]
+```
+
+- **bot_id**: Canonical bot ID (e.g. `openclaw.france.prod-1`).
+- **operator_id**: Operator that owns the bot (e.g. `org.openclaw.pat`).
+- **ttl_sec** (optional): Token lifetime in seconds (default 300).
+
+Output is the raw JWT string on stdout. Use it as the password when connecting to the MQTT broker with username = `bot_id`.
+
+## Environment
+
+- **IDENTITY_SERVICE_URL** (required): Base URL of the identity service (e.g. `http://localhost:8080`).
+
+Keys are stored under `~/.openclaw/keys/<bot_id>.key`. Do not share or commit this file.
+
+---
+
+## Packaging and deployment (OpenClaw skills and plugins)
+
+This skill is designed to be **small and thin** on the bot. The heavy lifting (ledger, HTTP service, operator CLI) stays on the operator’s machine; bots only need:
+
+- A private key file under `~/.openclaw/keys/<bot_id>.key`.
+- Network access to the identity service (`IDENTITY_SERVICE_URL`).
+- A thin identity client library (for example, the `@clanker-chain/identity-plugin` package) that this skill can import.
+
+### Skills vs plugins
+
+Per the [OpenClaw Skills docs](https://www.learnclawdbot.org/docs/tools/skills):
+
+- A **skill** is a directory with a `SKILL.md` manifest that describes tools/commands.
+- Skills can be:
+  - Workspace skills (e.g. `skills/identity` in this repo).
+  - Plugin‑provided skills, listed in a plugin’s `openclaw.plugin.json`.
+
+Per the [OpenClaw plugin docs](https://docs.openclaw.ai/plugin):
+
+- Every plugin has an `openclaw.plugin.json` with an `id`, `name`, `description`, and `configSchema`.
+- Plugins can ship their own skills by listing skill directories (paths relative to the plugin root) in the manifest.
+
+This repo provides the **skill manifest and CLI wrapper** (`run.mjs`); you typically package the identity client code itself as a plugin/extension in your OpenClaw environment and point this skill at it.
+
+### Typical packaging flow
+
+1. Install the Clanker Chain identity plugin: `openclaw plugins install @clanker-chain/identity-plugin`, or in your OpenClaw plugin or bot image source repo, add the plugin (see `identity/SERVICE.md` for example manifests).
+2. In your Dockerfile for bot images (on the Ubuntu host), ensure the identity plugin is available so that:
+
+   ```js
+   import { IdentityClient } from "@clanker-chain/identity-plugin";
+   ```
+
+   resolves inside `run.mjs` (e.g. by installing `@clanker-chain/identity-plugin` in the skill or app).
+3. Copy only `SKILL.md` (and optionally `run.mjs`) into `skills/identity/` in the image, or point the plugin’s `skills` array at your workspace skill directory.
+
+With this setup, bots do not need any of the identity service or ledger code; they only need:
+
+- The **extension** providing the identity client library.
+- This **skill** describing how to call it.
+- Their own private key and the identity service URL.
+
+---
+
+## Error handling
+
+Common failure modes and what they mean:
+
+- **Service unreachable / connection error**: treat as infrastructure outage; retry with backoff, and surface that the identity service is offline.
+- **\"Operator not registered\"** from `identity_init`: the operator has not been minted into the ledger; run genesis or `mint-operator` first.
+- **\"Bot not registered or key not found\"** from `identity_init`: the bot has not been minted with this public key; rerun the operator-side mint-bot-token flow and POST to `/v1/bots`.
+- **Missing key file**: if `~/.openclaw/keys/{bot_id}.key` does not exist or is unreadable, the bot cannot sign; fix key provisioning rather than silently generating a new key.

package/src/skill/run.mjs

@@ -0,0 +1,208 @@
+#!/usr/bin/env node
+/**
+ * Runner for the identity skill. Invoke from OpenClaw via exec.
+ *
+ * Usage:
+ *   node run.mjs init <bot_id> <operator_id>
+ *   node run.mjs verify <bot_id> <operator_id>
+ *   node run.mjs get-bot <bot_id>
+ *   node run.mjs sign '<envelope_json>'
+ *   node run.mjs issue-mqtt-token <bot_id> <operator_id> [ttl_sec]
+ *
+ * Env: IDENTITY_SERVICE_URL.
+ */
+
+import { IdentityClient } from "@clanker-chain/identity-plugin";
+
+const [,, cmd, ...args] = process.argv;
+
+function usage() {
+  console.error(`Usage:
+  node run.mjs init <bot_id> <operator_id>
+  node run.mjs verify <bot_id> <operator_id>
+  node run.mjs get-bot <bot_id>
+  node run.mjs sign '<envelope_json>'
+  node run.mjs issue-mqtt-token <bot_id> <operator_id> [ttl_sec]
+`);
+}
+
+async function main() {
+  if (!cmd) {
+    usage();
+    process.exit(1);
+  }
+
+  try {
+    if (cmd === "init") {
+      const [botId, operatorId] = args;
+      if (!botId || !operatorId) {
+        console.error("identity init requires bot_id and operator_id");
+        usage();
+        process.exit(1);
+      }
+      const client = new IdentityClient({ botId, operatorId });
+      const identityServiceUrl = process.env.IDENTITY_SERVICE_URL ?? "http://localhost:8080";
+
+      const publicKey = await client.getPublicKeyBase64();
+      await client.init();
+      const bot = await client.getBot();
+      const hasActiveKey =
+        Array.isArray(bot.public_keys) &&
+        bot.public_keys.some((k) => k.public_key === publicKey && k.status === "active");
+
+      console.log(
+        JSON.stringify({
+          ok: true,
+          bot_id: botId,
+          operator_id: operatorId,
+          identity_service_url: identityServiceUrl,
+          public_key: publicKey,
+          bot_has_active_key: hasActiveKey,
+          bot,
+        }),
+      );
+      return;
+    }
+
+    if (cmd === "verify") {
+      const [botId, operatorId] = args;
+      if (!botId || !operatorId) {
+        console.error("identity verify requires bot_id and operator_id");
+        usage();
+        process.exit(1);
+      }
+
+      const identityServiceUrl = process.env.IDENTITY_SERVICE_URL ?? "http://localhost:8080";
+      const client = new IdentityClient({ botId, operatorId });
+
+      const result = {
+        ok: false,
+        bot_id: botId,
+        operator_id: operatorId,
+        identity_service_url: identityServiceUrl,
+        operator: { exists: false },
+        bot: { exists: false },
+        key: { matches: false, public_key: undefined },
+        error: undefined,
+      };
+
+      try {
+        const publicKey = await client.getPublicKeyBase64();
+        result.key.public_key = publicKey;
+
+        const opRes = await fetch(
+          `${identityServiceUrl}/v1/operators/${encodeURIComponent(operatorId)}`,
+        );
+        if (!opRes.ok) {
+          const text = await opRes.text();
+          result.error =
+            text || `operator lookup failed with status ${opRes.status}`;
+          console.log(JSON.stringify(result));
+          return;
+        }
+        result.operator.exists = true;
+
+        const botRes = await fetch(
+          `${identityServiceUrl}/v1/bots/${encodeURIComponent(botId)}`,
+        );
+        if (!botRes.ok) {
+          const text = await botRes.text();
+          result.error = text || `bot lookup failed with status ${botRes.status}`;
+          console.log(JSON.stringify(result));
+          return;
+        }
+        const bot = await botRes.json();
+        result.bot.exists = true;
+
+        const hasKey =
+          Array.isArray(bot.public_keys) &&
+          bot.public_keys.some(
+            (k) =>
+              k.public_key === publicKey && k.status === "active",
+          );
+        result.key.matches = hasKey;
+
+        if (!hasKey) {
+          result.error =
+            "bot exists but does not have an active public key matching the local key";
+          console.log(JSON.stringify(result));
+          return;
+        }
+
+        result.ok = true;
+        console.log(JSON.stringify(result));
+        return;
+      } catch (err) {
+        result.error = (err && err.message) || String(err);
+        console.log(JSON.stringify(result));
+        return;
+      }
+    }
+
+    if (cmd === "get-bot") {
+      const [botId] = args;
+      if (!botId) {
+        console.error("identity get-bot requires bot_id");
+        usage();
+        process.exit(1);
+      }
+      const client = new IdentityClient({ botId, operatorId: "" });
+      const bot = await client.getBot();
+      console.log(JSON.stringify(bot));
+      return;
+    }
+
+    if (cmd === "sign") {
+      const [envelopeJson] = args;
+      if (!envelopeJson) {
+        console.error("identity sign requires envelope JSON string");
+        usage();
+        process.exit(1);
+      }
+      const envelope = JSON.parse(envelopeJson);
+      const botId = envelope.from_id;
+      const operatorId = envelope.operator_id;
+      if (!botId || !operatorId) {
+        console.error("envelope must include from_id and operator_id");
+        process.exit(1);
+      }
+      const client = new IdentityClient({ botId, operatorId });
+      const { signature, signature_scheme } = await client.signMessage(envelope);
+      console.log(
+        JSON.stringify({
+          signature,
+          signature_scheme,
+          envelope: { ...envelope, signature, signature_scheme },
+        }),
+      );
+      return;
+    }
+
+    if (cmd === "issue-mqtt-token") {
+      const [botId, operatorId, ttlSecStr] = args;
+      if (!botId || !operatorId) {
+        console.error("identity issue-mqtt-token requires bot_id and operator_id");
+        usage();
+        process.exit(1);
+      }
+      const ttlSec = ttlSecStr ? parseInt(ttlSecStr, 10) : 300;
+      if (Number.isNaN(ttlSec) || ttlSec < 1) {
+        console.error("ttl_sec must be a positive number");
+        process.exit(1);
+      }
+      const client = new IdentityClient({ botId, operatorId });
+      const token = await client.issueMqttToken(ttlSec);
+      console.log(token);
+      return;
+    }
+
+    console.error("Unknown command:", cmd);
+    usage();
+    process.exit(1);
+  } catch (err) {
+    console.error(JSON.stringify({ error: (err && err.message) || String(err) }));
+    process.exit(1);
+  }
+}
+
+main();

package/src/types.ts

@@ -0,0 +1,51 @@
+export type PublicKeyStatus = "active" | "revoked";
+
+export interface PublicKeyRecord {
+  key_id: string;
+  algorithm: string;
+  public_key: string;
+  created: string;
+  status: PublicKeyStatus;
+  metadata?: Record<string, unknown>;
+}
+
+export interface OperatorRecord {
+  operator_id: string;
+  display_name?: string;
+  public_keys?: PublicKeyRecord[];
+  status: "active" | "suspended" | "retired";
+  created: string;
+  updated: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface BotRecord {
+  bot_id: string;
+  display_name?: string;
+  operator_id: string;
+  aliases?: string[];
+  public_keys?: PublicKeyRecord[];
+  status: "active" | "suspended" | "retired";
+  created: string;
+  updated: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface IdentityMessageEnvelope {
+  from: string;
+  from_id: string;
+  operator_id: string;
+  to?: string;
+  to_id?: string;
+  type: string;
+  subtype?: string;
+  channel?: string;
+  timestamp: string;
+  message_id: string;
+  correlation_id?: string;
+  privacy?: "default" | "private" | "encrypted";
+  encrypted?: boolean;
+  encryption_scheme?: string | null;
+  identity_token?: string | null;
+  body: unknown;
+}

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "node",
+    "strict": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true,
+    "outDir": "dist"
+  },
+  "include": ["src/**/*", "index.ts"]
+}