@reefclaw/openclaw-plugin 0.1.0

package/bridge/utils/skill-signing.js

@@ -0,0 +1,138 @@
+// Ed25519 signature verification for OTA SKILL.md updates.
+//
+// Security finding C1 (docs/PRE_LAUNCH_SECURITY_HARDENING.md §2.5 + Appendix B):
+// the relay is treated as a DUMB TRANSPORT. A pushed/pulled SKILL.md is applied
+// only if it carries a valid signature from the operator's offline private key,
+// whose PUBLIC key is pinned here in the build. A leaked ADMIN_SECRET, a
+// compromised relay process, or a tampered Durable-Object value therefore
+// CANNOT rewrite an agent's trading instructions — they all fail verification.
+//
+// Key provisioning (one-time, operator, OFFLINE):
+//   1. python scripts/gen-skill-signing-key.py
+//   2. paste the printed PUBLIC key (base64) into TRUSTED_SKILL_SIGNING_KEYS below
+//   3. put the printed PRIVATE key into .env.deploy as SKILL_SIGNING_PRIVATE_KEY
+//      (gitignored — keep it offline; NEVER on the relay or any server)
+//   4. rebuild + redeploy the skill (deploy-skillmd-ota.py is already wired to sign)
+//
+// Until a key is pinned, OTA is FAIL-CLOSED (every push rejected) while
+// SKILL_OTA_REQUIRE_SIGNATURE is on (the default). Normal trading is unaffected
+// — only the OTA-update path gates on this.
+import { createHash, createPublicKey, verify as cryptoVerify } from 'node:crypto';
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { parseSkillVersion } from './skill-version.js';
+/**
+ * Pinned Ed25519 PUBLIC keys (base64 of the raw 32-byte key) trusted to sign OTA
+ * SKILL.md updates. Multiple entries enable key rotation (accept current + next,
+ * retire the old after every client has updated). EMPTY until the operator pins
+ * one — see the header for provisioning.
+ */
+export const TRUSTED_SKILL_SIGNING_KEYS = [
+// 'Base64OfRaw32BytePublicKey=' ← paste from scripts/gen-skill-signing-key.py
+];
+const OTA_STATE_PATH = join(homedir(), '.openclaw', 'workspace', '.skill-ota-state.json');
+/** Lowercase hex SHA-256 of the UTF-8 content. MUST match the Python signer. */
+export function sha256Hex(content) {
+    return createHash('sha256').update(content, 'utf8').digest('hex');
+}
+/** Canonical signed message — MUST match deploy-skillmd-ota.py byte-for-byte. */
+export function signedMessage(version, contentSha256, signedAt) {
+    return `${version}\n${contentSha256}\n${signedAt}`;
+}
+/**
+ * Is OTA signature verification enforced?
+ *
+ * Default **OFF** while C1 (signed OTA) is ON HOLD — see
+ * docs/PRE_LAUNCH_SECURITY_HARDENING.md §2.5. Keeping it off by default makes
+ * this whole module DORMANT, so deploying skill/relay for UNRELATED reasons can
+ * never break the existing (unsigned) OTA flow — no env flag to remember.
+ *
+ * To ENABLE signed-OTA (when the agent-update mechanism is finalized): pin a
+ * public key in TRUSTED_SKILL_SIGNING_KEYS **and** set
+ * SKILL_OTA_REQUIRE_SIGNATURE=on. Both are required — a pinned key alone does
+ * nothing without the flag, and the flag alone fails closed (no key → reject).
+ */
+export function signatureRequired() {
+    return (process.env.SKILL_OTA_REQUIRE_SIGNATURE ?? 'off').toLowerCase() === 'on';
+}
+function publicKeyFromRawB64(b64) {
+    try {
+        const raw = Buffer.from(b64, 'base64');
+        if (raw.length !== 32)
+            return null; // raw Ed25519 public key is exactly 32 bytes
+        return createPublicKey({
+            format: 'jwk',
+            key: { kty: 'OKP', crv: 'Ed25519', x: raw.toString('base64url') },
+        });
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Verify a signed OTA envelope against the pinned (or supplied) trusted keys.
+ * Checks: required fields present, content hash matches (no tampering), the
+ * frontmatter version matches the signed version (no number-bump replay), and
+ * the Ed25519 signature verifies under some trusted key. Pure — does NOT touch
+ * disk or the replay clock; the caller enforces monotonic signedAt.
+ */
+export function verifySkillSignature(env, opts) {
+    const keys = opts?.trustedKeys ?? TRUSTED_SKILL_SIGNING_KEYS;
+    if (keys.length === 0) {
+        return { ok: false, reason: 'no trusted signing keys configured — pin a public key in skill-signing.ts (see scripts/gen-skill-signing-key.py)' };
+    }
+    if (!env.signature || !env.signedAt || !env.contentSha256) {
+        return { ok: false, reason: 'missing signature/signedAt/contentSha256 (unsigned push)' };
+    }
+    if (sha256Hex(env.content) !== env.contentSha256) {
+        return { ok: false, reason: 'content hash mismatch (tampered content)' };
+    }
+    const frontmatterVersion = parseSkillVersion(env.content);
+    if (frontmatterVersion !== env.version) {
+        return { ok: false, reason: `version mismatch (envelope ${env.version} vs frontmatter ${frontmatterVersion ?? 'none'})` };
+    }
+    const msg = Buffer.from(signedMessage(env.version, env.contentSha256, env.signedAt), 'utf8');
+    let sig;
+    try {
+        sig = Buffer.from(env.signature, 'base64');
+    }
+    catch {
+        return { ok: false, reason: 'signature is not valid base64' };
+    }
+    for (const keyB64 of keys) {
+        const pub = publicKeyFromRawB64(keyB64);
+        if (!pub)
+            continue;
+        try {
+            if (cryptoVerify(null, msg, pub, sig))
+                return { ok: true };
+        }
+        catch {
+            /* malformed key/sig for this candidate — try the next */
+        }
+    }
+    return { ok: false, reason: 'signature does not verify under any trusted key' };
+}
+/** Last applied signedAt as epoch ms, 0 if none/unreadable (replay clock). */
+export function readLastAppliedSignedAtMs() {
+    try {
+        const raw = readFileSync(OTA_STATE_PATH, 'utf-8');
+        const t = JSON.parse(raw).lastAppliedSignedAt;
+        const ms = t ? new Date(t).getTime() : 0;
+        return Number.isFinite(ms) ? ms : 0;
+    }
+    catch {
+        return 0;
+    }
+}
+/** Persist the signedAt of the just-applied update (monotonic replay clock). */
+export function recordAppliedSignedAt(signedAt) {
+    try {
+        mkdirSync(join(homedir(), '.openclaw', 'workspace'), { recursive: true });
+        writeFileSync(OTA_STATE_PATH, JSON.stringify({ lastAppliedSignedAt: signedAt }), 'utf-8');
+    }
+    catch {
+        /* best-effort — if this fails the replay window is bounded to one process life */
+    }
+}

package/bridge/utils/skill-version.d.ts

@@ -0,0 +1,17 @@
+/** Extract version from SKILL.md frontmatter */
+export declare function parseSkillVersion(content: string): string | null;
+/** Read current SKILL.md version from disk */
+export declare function readLocalSkillVersion(): string | null;
+/**
+ * Compare two semver strings.
+ * Returns 1 if a > b, -1 if a < b, 0 if equal.
+ * Non-semver inputs (or null) are treated as -Infinity so a valid semver always
+ * wins, which is the safe direction for "should I accept this OTA push?".
+ */
+export declare function compareSemver(a: string | null, b: string | null): number;
+/** Validate SKILL.md content is well-formed */
+export declare function validateSkillContent(content: string): {
+    valid: boolean;
+    version: string | null;
+    error?: string;
+};

package/bridge/utils/skill-version.js

@@ -0,0 +1,74 @@
+// SKILL.md version parsing utility for OTA updates
+import { readFileSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+const SKILL_MD_PATH = join(homedir(), '.openclaw', 'workspace', 'SKILL.md');
+/** Extract version from SKILL.md frontmatter */
+export function parseSkillVersion(content) {
+    const match = content.match(/^---[\s\S]*?version:\s*(\S+)[\s\S]*?---/);
+    return match ? match[1] : null;
+}
+/** Read current SKILL.md version from disk */
+export function readLocalSkillVersion() {
+    try {
+        const content = readFileSync(SKILL_MD_PATH, 'utf-8');
+        return parseSkillVersion(content);
+    }
+    catch {
+        return null;
+    }
+}
+// 120KB — the full SKILL.md crossed 100KB at v2.20.0 (103.7KB), which silently
+// broke every OTA apply against the old 100KB cap. Keep comfortably under the
+// 128KiB Cloudflare Durable-Object per-value hard limit the relay stores into.
+const MAX_SKILL_CONTENT_SIZE = 120_000;
+const SEMVER_REGEX = /^\d+\.\d+\.\d+$/;
+/**
+ * Compare two semver strings.
+ * Returns 1 if a > b, -1 if a < b, 0 if equal.
+ * Non-semver inputs (or null) are treated as -Infinity so a valid semver always
+ * wins, which is the safe direction for "should I accept this OTA push?".
+ */
+export function compareSemver(a, b) {
+    const parse = (v) => {
+        if (!v || !SEMVER_REGEX.test(v))
+            return null;
+        const [maj, min, pat] = v.split('.').map(Number);
+        return [maj, min, pat];
+    };
+    const pa = parse(a);
+    const pb = parse(b);
+    if (!pa && !pb)
+        return 0;
+    if (!pa)
+        return -1;
+    if (!pb)
+        return 1;
+    for (let i = 0; i < 3; i++) {
+        if (pa[i] > pb[i])
+            return 1;
+        if (pa[i] < pb[i])
+            return -1;
+    }
+    return 0;
+}
+/** Validate SKILL.md content is well-formed */
+export function validateSkillContent(content) {
+    if (content.length > MAX_SKILL_CONTENT_SIZE) {
+        return { valid: false, version: null, error: `Content too large (${content.length} bytes, max ${MAX_SKILL_CONTENT_SIZE})` };
+    }
+    if (!content.startsWith('---')) {
+        return { valid: false, version: null, error: 'Missing frontmatter delimiter' };
+    }
+    const version = parseSkillVersion(content);
+    if (!version) {
+        return { valid: false, version: null, error: 'No version in frontmatter' };
+    }
+    if (!SEMVER_REGEX.test(version)) {
+        return { valid: false, version, error: `Invalid version format: ${version} (expected semver x.y.z)` };
+    }
+    if (content.length < 100) {
+        return { valid: false, version, error: 'Content suspiciously short' };
+    }
+    return { valid: true, version };
+}

package/ccxt/binance-ban-gate.d.ts

@@ -0,0 +1,47 @@
+/** Thrown by `assertNotBanned` while the gate is closed. Carries the
+ *  remaining cooldown so callers/telemetry can reason about it. Methods
+ *  catch this in their existing catch block — it is NOT meant to escape
+ *  the API layer with special handling; it degrades to the method's normal
+ *  failure contract. */
+export declare class BinanceBannedError extends Error {
+    readonly retryAfterMs: number;
+    constructor(retryAfterMs: number, context: string);
+}
+/** Thrown by the proactive weight pacer. Subclass of BinanceBannedError so
+ *  every `instanceof BinanceBannedError` check and every method's existing
+ *  catch keep working unchanged — it degrades to the same null/[]/throw
+ *  contract (treated exactly like a transient fetch failure). The distinct
+ *  name lets journal/telemetry tell prevention apart from a real IP ban. */
+export declare class BinanceWeightPacedError extends BinanceBannedError {
+    constructor(retryAfterMs: number, context: string);
+}
+/** Fast pre-flight check. Call as the first line inside a Binance call's
+ *  try-block. Throws `BinanceBannedError` (no network) while the gate is
+ *  open. */
+export declare function assertNotBanned(context: string): void;
+/** Inspect a failed call's error and arm/extend the gate on a Binance
+ *  rate-limit signal. Non-rate-limit errors are ignored (normal transient
+ *  handling stays in the caller). Safe to call with any error shape. */
+export declare function noteBinanceError(err: unknown): void;
+/** Relax the soft-429 ladder after a clean call. (A hard 418 window is NOT
+ *  shortened by this — only Binance's stated expiry clears it.) */
+export declare function noteSuccess(): void;
+/** Reconcile the local weight estimate against Binance truth from a response
+ *  header (`x-mbx-used-weight-1m`). Best-effort: callers pass whatever header
+ *  bag they have; absent/garbage values are ignored. The local estimate
+ *  leads (counts in-flight calls Binance hasn't tallied yet), so we take the
+ *  MAX within the window — never let a lagging header lower our guard. A
+ *  header far BELOW the estimate means Binance's minute rolled; re-anchor the
+ *  window to Binance's clock so we don't shed for a stale local total. */
+export declare function noteResponseWeight(headers: Record<string, string> | undefined | null): void;
+/** Test/diagnostic helper — current gate state. */
+export declare function getBanGateState(): {
+    banUntilMs: number;
+    remainingMs: number;
+    rateLimitStep: number;
+    weightUsed: number;
+    weightCeiling: number;
+    cosmeticCeiling: number;
+};
+/** Test-only reset. Not used in production code paths. */
+export declare function __resetBanGateForTests(): void;