ppq-private-mode 0.1.0

package/README.md

@@ -0,0 +1,145 @@
+# How to use PPQ's Private (TEE) AI models via our API and with OpenClaw
+
+> Your queries are encrypted on your machine and only decrypted inside a hardware-secured enclave. Neither PPQ.AI nor any intermediary can read the content.
+
+This guide walks you through setting up the PPQ private mode proxy. You can follow these steps from either a terminal or the OpenClaw chat interface.
+
+> **Install via the OpenClaw Chat interface or Command line:** Some users report that they are able to install the plugin and update their config files by simply giving the OpenClaw chat interface these instructions. Others report issues. If you encounter problems in the chat, you may need to open a terminal connected to your OpenClaw instance and do it that way.
+
+## What You'll Need
+
+- An OpenClaw installation (already running)
+- A PPQ.AI API key -- get one at https://ppq.ai/api-docs (it starts with `sk-`)
+
+## Step 1: Install the Private Mode Plugin
+
+Run this command to install the plugin:
+
+```
+openclaw plugins install https://github.com/PayPerQ/ppq-private-mode-proxy
+```
+
+This downloads a local encryption proxy that handles all the cryptography on your machine.
+
+To verify it installed correctly:
+
+```
+ls ~/.openclaw/plugins/ppq-private-mode/
+```
+
+You should see files like `index.ts`, `package.json`, etc.
+
+## Step 2: Add Your API Key and Models to OpenClaw Config
+
+You need to edit your OpenClaw config file at `~/.openclaw/openclaw.json` and add two things: a provider pointing to the local proxy, and your API key.
+
+If you already have a `models.providers` section, merge this in -- don't overwrite your existing providers.
+
+**Add this provider** under `models.providers`:
+
+```json
+"ppq-private": {
+  "baseUrl": "http://127.0.0.1:8787/v1",
+  "apiKey": "unused",
+  "api": "openai-completions",
+  "models": [
+    { "id": "private/kimi-k2-5", "name": "private/kimi-k2-5" },
+    { "id": "private/deepseek-r1-0528", "name": "private/deepseek-r1-0528" },
+    { "id": "private/gpt-oss-120b", "name": "private/gpt-oss-120b" },
+    { "id": "private/llama3-3-70b", "name": "private/llama3-3-70b" },
+    { "id": "private/qwen3-vl-30b", "name": "private/qwen3-vl-30b" }
+  ]
+}
+```
+
+**Add this plugin config** (replace `YOUR_API_KEY` with your actual PPQ API key):
+
+```json
+"plugins": {
+  "entries": {
+    "ppq-private-mode": {
+      "config": {
+        "apiKey": "YOUR_API_KEY"
+      }
+    }
+  }
+}
+```
+
+**Chat interface shortcut:** You can tell OpenClaw: *"Please add the ppq-private provider to my openclaw.json config. Here's the JSON to merge in:"* and paste the blocks above. The AI can edit config files for you.
+
+## Step 3: Restart the Gateway
+
+```
+systemctl --user restart openclaw-gateway.service
+```
+
+This starts the local encryption proxy and connects it to your OpenClaw instance.
+
+## Step 4: Switch to a Private Model
+
+```
+openclaw models set private/kimi-k2-5
+```
+
+That's it! Your queries are now end-to-end encrypted. You may need to start a new chat session for the model change to take effect.
+
+## Available Private Models
+
+| Model | Best For |
+|-------|----------|
+| `private/kimi-k2-5` | **Recommended.** Fast general tasks, 262K context window |
+| `private/deepseek-r1-0528` | Reasoning and analysis |
+| `private/gpt-oss-120b` | Budget-friendly general use |
+| `private/llama3-3-70b` | Open-source tasks |
+| `private/qwen3-vl-30b` | Vision + text, 262K context window |
+
+Switch between them anytime with `openclaw models set <model-name>`.
+
+## How It Works
+
+The plugin runs a local proxy on your machine (port 8787) that:
+
+1. **Verifies the enclave** -- performs hardware attestation to confirm it's talking to a genuine secure enclave, not an impersonator
+2. **Encrypts your request** -- uses HPKE (RFC 9180) to encrypt the entire request body before it leaves your machine
+3. **Sends the encrypted blob** -- PPQ.AI routes the encrypted data to the secure enclave. PPQ.AI only sees ciphertext.
+4. **Enclave processes privately** -- the enclave decrypts your query, runs the AI model, and re-encrypts the response
+5. **Your proxy decrypts** -- the response is decrypted locally on your machine
+
+PPQ.AI handles billing via HTTP headers (your API key), so they never need to see the actual content of your queries.
+
+## Using Private Mode Alongside Regular Models
+
+Your existing OpenClaw models continue working normally. Standard models (like Claude, GPT, etc.) use their regular API routes, while private models route through the encrypted proxy. Both can coexist in your config, and you can switch between them anytime.
+
+## Troubleshooting
+
+**"Authentication error" or "Protocol error"**
+Your API key may be wrong or your account balance is low. Check at https://ppq.ai
+
+**"Attestation failed"**
+The secure enclave may be temporarily unavailable. Wait a few minutes and restart:
+```
+systemctl --user restart openclaw-gateway.service
+```
+
+**Port conflict on 8787**
+If something else is using port 8787, add a different port to your plugin config in `openclaw.json`:
+```json
+"ppq-private-mode": {
+  "config": {
+    "apiKey": "YOUR_API_KEY",
+    "port": 8788
+  }
+}
+```
+
+**Plugin not found after install**
+Make sure `~/.openclaw/plugins/ppq-private-mode/` exists. If not, re-run the install command from Step 1.
+
+**Checking proxy status**
+Use the `ppq_private_mode_status` tool in OpenClaw to verify the proxy is running and attestation succeeded.
+
+## About
+
+PPQ.AI provides pay-per-query AI inference with no subscriptions. Private models run inside secure enclaves with hardware-enforced memory encryption. Learn more at https://ppq.ai

package/bin/server.ts

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+/**
+ * Standalone entry point for the PPQ Private Mode proxy.
+ *
+ * Usage:
+ *   PPQ_API_KEY=sk-xxx npx tsx bin/server.ts
+ *
+ * Environment variables:
+ *   PPQ_API_KEY   (required) — Your PPQ.AI API key from https://ppq.ai/api-docs
+ *   PORT          (optional) — Proxy port, default 8787
+ *   PPQ_API_BASE  (optional) — API base URL, default https://api.ppq.ai
+ *   DEBUG         (optional) — Set to "true" for verbose logging
+ */
+
+import { startProxy } from "../lib/proxy.js";
+
+const apiKey = process.env.PPQ_API_KEY;
+if (!apiKey) {
+  console.error("Error: PPQ_API_KEY environment variable is required");
+  console.error("Get your API key from https://ppq.ai/api-docs");
+  process.exit(1);
+}
+
+const port = parseInt(process.env.PORT || "8787", 10);
+const apiBase = process.env.PPQ_API_BASE || "https://api.ppq.ai";
+const debug = process.env.DEBUG === "true";
+
+const proxy = await startProxy(
+  { apiKey, port, apiBase, debug },
+  {
+    info: (msg) => console.log(msg),
+    error: (msg) => console.error(msg),
+    debug: debug ? (msg) => console.log(`[debug] ${msg}`) : undefined,
+  }
+);
+
+console.log("");
+console.log("Send a test request:");
+console.log(`  curl http://127.0.0.1:${proxy.port}/v1/chat/completions \\`);
+console.log(`    -H "Content-Type: application/json" \\`);
+console.log(`    -d '{"model":"private/kimi-k2-5","messages":[{"role":"user","content":"Hello"}]}'`);
+console.log("");
+
+// Graceful shutdown
+for (const sig of ["SIGINT", "SIGTERM"] as const) {
+  process.on(sig, async () => {
+    console.log("\nShutting down...");
+    await proxy.close();
+    process.exit(0);
+  });
+}

package/index.ts

@@ -0,0 +1,247 @@
+/**
+ * PPQ Private Mode — OpenClaw Plugin
+ *
+ * Registers a local proxy service that encrypts AI requests using EHBP
+ * before forwarding to PPQ.AI's private inference endpoints. This ensures
+ * end-to-end encryption: neither PPQ.AI nor any intermediary can read your queries.
+ *
+ * Install:
+ *   1. Copy this plugin directory to your OpenClaw plugins folder
+ *   2. Run `npm install` in the plugin directory
+ *   3. Add your PPQ API key in OpenClaw settings
+ *   4. Set model to any private model (e.g. private/kimi-k2-5)
+ */
+
+import { startProxy, type ProxyHandle, type ProxyConfig } from "./lib/proxy.js";
+
+export const id = "ppq-private-mode";
+export const name = "PPQ Private Mode";
+
+interface PluginConfig {
+  apiKey?: string;
+  port?: number;
+  apiBase?: string;
+  debug?: boolean;
+}
+
+let proxy: ProxyHandle | null = null;
+
+export default function register(api: any) {
+  const pluginConfig: PluginConfig =
+    api.config?.plugins?.entries?.["ppq-private-mode"]?.config || {};
+
+  // ─── MCP Tool: check proxy status ───────────────────────────────────────────
+
+  api.registerTool(
+    {
+      name: "ppq_private_mode_status",
+      description:
+        "Check status of the PPQ Private Mode proxy (attestation, health, endpoints)",
+      parameters: { type: "object", properties: {} },
+      async execute() {
+        if (!pluginConfig.apiKey) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify({
+                  status: "not_configured",
+                  message:
+                    "PPQ API key not configured. Set it in OpenClaw settings under PPQ Private Mode.",
+                  setup: {
+                    step1: "Get a PPQ.AI API key from https://ppq.ai/settings",
+                    step2: 'Add your key to the plugin config: { "apiKey": "your-key" }',
+                    step3: "Restart OpenClaw",
+                  },
+                }),
+              },
+            ],
+          };
+        }
+
+        if (!proxy) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify({
+                  status: "not_running",
+                  message: "Private Mode proxy is not running. It may be starting up.",
+                }),
+              },
+            ],
+          };
+        }
+
+        // Health check
+        try {
+          const resp = await fetch(`http://127.0.0.1:${proxy.port}/health`);
+          const health = await resp.json();
+
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify({
+                  status: "running",
+                  healthy: resp.ok,
+                  port: proxy.port,
+                  baseUrl: `http://127.0.0.1:${proxy.port}`,
+                  attestation: {
+                    verified: !!proxy.verification,
+                    enclaveHost: proxy.verification?.enclaveHost || null,
+                    codeFingerprint: proxy.verification?.codeFingerprint || null,
+                  },
+                  endpoints: {
+                    models: `http://127.0.0.1:${proxy.port}/v1/models`,
+                    chat: `http://127.0.0.1:${proxy.port}/v1/chat/completions`,
+                  },
+                  availableModels: [
+                    "private/kimi-k2-5",
+                    "private/deepseek-r1-0528",
+                    "private/gpt-oss-120b",
+                    "private/llama3-3-70b",
+                    "private/qwen3-vl-30b",
+                  ],
+                }),
+              },
+            ],
+          };
+        } catch {
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify({
+                  status: "unhealthy",
+                  message: "Proxy is registered but health check failed.",
+                }),
+              },
+            ],
+          };
+        }
+      },
+    },
+    { optional: true }
+  );
+
+  // ─── Provider: expose private models to OpenClaw ────────────────────────────
+
+  api.registerProvider({
+    id: "ppq-private-mode",
+    label: "PPQ Private Mode (End-to-End Encrypted)",
+    docsPath: "./skills/private-mode",
+    models: {
+      baseUrl: `http://127.0.0.1:${pluginConfig.port || 8787}`,
+      api: "openai-completions",
+      models: [
+        {
+          id: "private/kimi-k2-5",
+          name: "Kimi K2.5 (Private)",
+          reasoning: false,
+          input: ["text"],
+          cost: { input: 2.48, output: 8.66, cacheRead: 0, cacheWrite: 0 },
+          contextWindow: 262144,
+          maxTokens: 8192,
+        },
+        {
+          id: "private/deepseek-r1-0528",
+          name: "DeepSeek R1 (Private)",
+          reasoning: true,
+          input: ["text"],
+          cost: { input: 2.48, output: 8.66, cacheRead: 0, cacheWrite: 0 },
+          contextWindow: 131072,
+          maxTokens: 8192,
+        },
+        {
+          id: "private/gpt-oss-120b",
+          name: "GPT-OSS 120B (Private)",
+          reasoning: false,
+          input: ["text"],
+          cost: { input: 1.24, output: 2.06, cacheRead: 0, cacheWrite: 0 },
+          contextWindow: 131072,
+          maxTokens: 8192,
+        },
+        {
+          id: "private/llama3-3-70b",
+          name: "Llama 3.3 70B (Private)",
+          reasoning: false,
+          input: ["text"],
+          cost: { input: 2.89, output: 4.54, cacheRead: 0, cacheWrite: 0 },
+          contextWindow: 131072,
+          maxTokens: 8192,
+        },
+        {
+          id: "private/qwen3-vl-30b",
+          name: "Qwen3-VL 30B (Private)",
+          reasoning: false,
+          input: ["text", "image"],
+          cost: { input: 2.06, output: 6.60, cacheRead: 0, cacheWrite: 0 },
+          contextWindow: 262144,
+          maxTokens: 8192,
+        },
+      ],
+    },
+    auth: [
+      {
+        id: "api_key",
+        label: "PPQ.AI API Key",
+        hint: "Get your API key from https://ppq.ai/settings",
+        kind: "api_key" as const,
+        async run(ctx: any) {
+          const key = await ctx.prompter.text({
+            message: "Enter your PPQ.AI API key:",
+            validate: (v: string) =>
+              v.trim().length > 0 ? undefined : "API key is required",
+          });
+          if (typeof key === "symbol") throw new Error("Setup cancelled");
+          return {
+            profiles: [{ profileId: "default", credential: { apiKey: key } }],
+            defaultModel: "private/kimi-k2-5",
+          };
+        },
+      },
+    ],
+  });
+
+  // ─── Service: manage proxy lifecycle ────────────────────────────────────────
+
+  api.registerService({
+    id: "ppq-private-mode-service",
+
+    async start() {
+      if (!pluginConfig.apiKey) {
+        api.logger.warn(
+          "PPQ Private Mode: no API key configured. Skipping proxy startup."
+        );
+        return;
+      }
+
+      const config: ProxyConfig = {
+        apiKey: pluginConfig.apiKey,
+        port: pluginConfig.port || 8787,
+        apiBase: pluginConfig.apiBase || "https://api.ppq.ai",
+        debug: pluginConfig.debug || false,
+      };
+
+      try {
+        proxy = await startProxy(config, {
+          info: (msg) => api.logger.info(`[private-mode] ${msg}`),
+          error: (msg) => api.logger.error(`[private-mode] ${msg}`),
+          debug: config.debug
+            ? (msg) => api.logger.info(`[private-mode:debug] ${msg}`)
+            : undefined,
+        });
+      } catch (err: any) {
+        api.logger.error(`Failed to start Private Mode proxy: ${err.message}`);
+      }
+    },
+
+    async stop() {
+      if (proxy) {
+        await proxy.close();
+        proxy = null;
+      }
+    },
+  });
+}

package/lib/proxy.ts

@@ -0,0 +1,314 @@
+/**
+ * PPQ Private Mode Proxy
+ *
+ * Runs a local OpenAI-compatible HTTP server that transparently encrypts
+ * requests using EHBP (SecureClient) before forwarding them to PPQ.AI's
+ * private inference endpoints. The proxy handles attestation, encryption,
+ * and response decryption — your client sees a standard OpenAI API at localhost.
+ *
+ * Flow:
+ *   Client → localhost:{port}/v1/chat/completions
+ *          → proxy encrypts body via EHBP (SecureClient.fetch)
+ *          → api.ppq.ai/private/v1/chat/completions
+ *          → secure enclave decrypts, runs inference
+ *          → encrypted response streams back
+ *          → proxy decrypts → plaintext stream to client
+ */
+
+import http from "node:http";
+import type { SecureClient, VerificationDocument } from "tinfoil";
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export interface ProxyConfig {
+  apiKey: string;
+  port: number;
+  apiBase: string;
+  debug: boolean;
+}
+
+export interface ProxyHandle {
+  port: number;
+  server: http.Server;
+  verification: VerificationDocument | null;
+  close: () => Promise<void>;
+}
+
+export interface Logger {
+  info: (msg: string) => void;
+  error: (msg: string) => void;
+  debug?: (msg: string) => void;
+}
+
+// ─── Constants ───────────────────────────────────────────────────────────────
+
+const DEFAULT_PORT = 8787;
+const DEFAULT_API_BASE = "https://api.ppq.ai";
+const HEALTH_TIMEOUT_MS = 15_000;
+
+/** Maps user-facing model IDs to enclave-internal model IDs */
+const PRIVATE_MODEL_MAP: Record<string, string> = {
+  "private/kimi-k2-5": "kimi-k2-5",
+  "private/deepseek-r1-0528": "deepseek-r1-0528",
+  "private/gpt-oss-120b": "gpt-oss-120b",
+  "private/llama3-3-70b": "llama3-3-70b",
+  "private/qwen3-vl-30b": "qwen3-vl-30b",
+};
+
+/** All available private model IDs (user-facing) */
+const PRIVATE_MODELS = Object.keys(PRIVATE_MODEL_MAP);
+
+/** OpenAI-format model list response */
+const MODEL_LIST_RESPONSE = {
+  object: "list",
+  data: [
+    {
+      id: "private/kimi-k2-5",
+      object: "model",
+      created: 0,
+      owned_by: "ppq-private",
+    },
+    {
+      id: "private/deepseek-r1-0528",
+      object: "model",
+      created: 0,
+      owned_by: "ppq-private",
+    },
+    {
+      id: "private/gpt-oss-120b",
+      object: "model",
+      created: 0,
+      owned_by: "ppq-private",
+    },
+    {
+      id: "private/llama3-3-70b",
+      object: "model",
+      created: 0,
+      owned_by: "ppq-private",
+    },
+    {
+      id: "private/qwen3-vl-30b",
+      object: "model",
+      created: 0,
+      owned_by: "ppq-private",
+    },
+  ],
+};
+
+// ─── Proxy server ────────────────────────────────────────────────────────────
+
+export async function startProxy(config: ProxyConfig, logger: Logger): Promise<ProxyHandle> {
+  const port = config.port || DEFAULT_PORT;
+  const apiBase = config.apiBase || DEFAULT_API_BASE;
+
+  // Dynamic import to avoid loading at module level
+  const { SecureClient: SC } = await import("tinfoil");
+
+  logger.info("Initializing encrypted connection to secure enclave...");
+
+  const client = new SC({
+    baseURL: `${apiBase}/private/`,
+    attestationBundleURL: `${apiBase}/private`,
+    transport: "ehbp",
+  });
+
+  // Perform attestation — verifies enclave code fingerprint
+  await client.ready();
+
+  let verification: VerificationDocument | null = null;
+  try {
+    verification = client.getVerificationDocument();
+    logger.info(
+      `Attestation verified — enclave: ${verification?.enclaveHost || "unknown"}, ` +
+        `code fingerprint: ${verification?.codeFingerprint?.slice(0, 16) || "unknown"}...`
+    );
+  } catch {
+    logger.info("Attestation completed (verification document unavailable)");
+  }
+
+  const encryptedFetch = client.fetch;
+
+  const server = http.createServer(async (req, res) => {
+    // CORS headers
+    res.setHeader("Access-Control-Allow-Origin", "*");
+    res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
+    res.setHeader("Access-Control-Allow-Headers", "Content-Type, Authorization");
+
+    if (req.method === "OPTIONS") {
+      res.writeHead(204);
+      res.end();
+      return;
+    }
+
+    const url = new URL(req.url || "/", `http://127.0.0.1:${port}`);
+
+    // GET /health
+    if (url.pathname === "/health" || url.pathname === "/") {
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ status: "ok", attestation: !!verification }));
+      return;
+    }
+
+    // GET /v1/models
+    if (url.pathname === "/v1/models" && req.method === "GET") {
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify(MODEL_LIST_RESPONSE));
+      return;
+    }
+
+    // POST /v1/chat/completions
+    if (url.pathname === "/v1/chat/completions" && req.method === "POST") {
+      try {
+        const body = await readBody(req);
+        const parsed = JSON.parse(body);
+
+        // Resolve model
+        let modelId: string = parsed.model || "private/kimi-k2-5";
+
+        // Ensure model is a valid private model
+        if (!PRIVATE_MODEL_MAP[modelId]) {
+          // Try adding private/ prefix
+          const prefixed = `private/${modelId}`;
+          if (PRIVATE_MODEL_MAP[prefixed]) {
+            modelId = prefixed;
+          } else {
+            res.writeHead(400, { "Content-Type": "application/json" });
+            res.end(
+              JSON.stringify({
+                error: {
+                  message: `Unknown model: ${parsed.model}. Available: ${PRIVATE_MODELS.join(", ")}`,
+                  type: "invalid_request_error",
+                },
+              })
+            );
+            return;
+          }
+        }
+
+        // Map to enclave-internal model ID
+        const enclaveModelId = PRIVATE_MODEL_MAP[modelId];
+        parsed.model = enclaveModelId;
+
+        if (config.debug) {
+          logger.debug?.(`→ ${modelId} (enclave: ${enclaveModelId}), stream: ${!!parsed.stream}`);
+        }
+
+        // Forward via SecureClient (EHBP-encrypted)
+        const endpoint = `${apiBase}/private/v1/chat/completions`;
+        const response = await encryptedFetch(endpoint, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${config.apiKey}`,
+            "X-Private-Model": modelId,
+            "x-query-source": "api",
+          },
+          body: JSON.stringify(parsed),
+        });
+
+        // Forward status and headers
+        const responseHeaders: Record<string, string> = {
+          "Content-Type": response.headers.get("content-type") || "application/json",
+          "Access-Control-Allow-Origin": "*",
+        };
+
+        if (parsed.stream) {
+          responseHeaders["Cache-Control"] = "no-cache";
+          responseHeaders["Connection"] = "keep-alive";
+        }
+
+        res.writeHead(response.status, responseHeaders);
+
+        // Stream the (decrypted) response body
+        if (response.body) {
+          const reader = response.body.getReader();
+          try {
+            while (true) {
+              const { done, value } = await reader.read();
+              if (done) break;
+              res.write(value);
+            }
+          } catch (err: any) {
+            if (config.debug) {
+              logger.error(`Stream error: ${err.message}`);
+            }
+          } finally {
+            res.end();
+          }
+        } else {
+          const text = await response.text();
+          res.end(text);
+        }
+      } catch (err: any) {
+        // Handle non-encrypted error responses (auth/balance errors from proxy)
+        if (err?.name === "ProtocolError") {
+          logger.error(`Protocol error (likely auth/balance issue): ${err.message}`);
+          res.writeHead(401, { "Content-Type": "application/json" });
+          res.end(
+            JSON.stringify({
+              error: {
+                message: "Authentication or balance error. Check your PPQ API key and account balance.",
+                type: "authentication_error",
+              },
+            })
+          );
+          return;
+        }
+
+        logger.error(`Request error: ${err.message}`);
+        res.writeHead(500, { "Content-Type": "application/json" });
+        res.end(
+          JSON.stringify({
+            error: {
+              message: err.message || "Internal proxy error",
+              type: "proxy_error",
+            },
+          })
+        );
+      }
+      return;
+    }
+
+    // 404 for everything else
+    res.writeHead(404, { "Content-Type": "application/json" });
+    res.end(
+      JSON.stringify({
+        error: {
+          message: `Unknown endpoint: ${req.method} ${url.pathname}`,
+          type: "invalid_request_error",
+        },
+      })
+    );
+  });
+
+  // Start listening
+  await new Promise<void>((resolve, reject) => {
+    server.on("error", reject);
+    server.listen(port, "127.0.0.1", () => {
+      logger.info(`PPQ Private Mode proxy listening on http://127.0.0.1:${port}`);
+      logger.info(`Endpoints: GET /v1/models, POST /v1/chat/completions`);
+      resolve();
+    });
+  });
+
+  return {
+    port,
+    server,
+    verification,
+    close: () =>
+      new Promise<void>((resolve) => {
+        server.close(() => resolve());
+      }),
+  };
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function readBody(req: http.IncomingMessage): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    req.on("data", (chunk) => chunks.push(chunk));
+    req.on("end", () => resolve(Buffer.concat(chunks).toString("utf-8")));
+    req.on("error", reject);
+  });
+}

package/openclaw.plugin.json

@@ -0,0 +1,24 @@
+{
+  "id": "ppq-private-mode",
+  "name": "PPQ Private Mode",
+  "description": "End-to-end encrypted AI inference via PPQ.AI. Runs a local proxy that encrypts your queries before they leave your machine.",
+  "version": "0.1.0",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "apiKey": { "type": "string" },
+      "port": { "type": "number" },
+      "apiBase": { "type": "string" },
+      "debug": { "type": "boolean" }
+    },
+    "required": ["apiKey"]
+  },
+  "uiHints": {
+    "apiKey": { "label": "PPQ.AI API Key", "sensitive": true },
+    "port": { "label": "Local Port", "placeholder": "8787" },
+    "apiBase": { "label": "PPQ API Base URL", "placeholder": "https://api.ppq.ai" },
+    "debug": { "label": "Debug Logging" }
+  },
+  "skills": ["./skills/private-mode"]
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "ppq-private-mode",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "End-to-end encrypted AI proxy for PPQ.AI private models. Works standalone or as an OpenClaw plugin.",
+  "openclaw": {
+    "extensions": ["./index.ts"]
+  },
+  "bin": {
+    "ppq-private-proxy": "./bin/server.ts"
+  },
+  "scripts": {
+    "start": "npx tsx bin/server.ts"
+  },
+  "files": ["index.ts", "lib", "bin", "skills", "openclaw.plugin.json"],
+  "dependencies": {
+    "tinfoil": "^1.0.0",
+    "zod": "^4.0.0"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.1.0"
+  },
+  "devDependencies": {
+    "tsx": "^4.0.0",
+    "typescript": "^5.7.0",
+    "@types/node": "^22.0.0"
+  }
+}

package/skills/private-mode/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: ppq-private-mode
+description: Configure PPQ.AI Private Mode encrypted models in OpenClaw
+user-invocable: true
+---
+
+# PPQ.AI Private Mode -- Configure Encrypted Models
+
+This skill configures OpenClaw to use PPQ.AI's end-to-end encrypted models. The PPQ Private Mode plugin must already be installed before running this skill.
+
+## Prerequisites
+
+The user must have already installed the PPQ Private Mode plugin. If it is not installed, tell the user to run this command themselves:
+
+    openclaw plugins install https://github.com/PayPerQ/ppq-private-mode-proxy
+
+Then ask the user to come back and run this skill again after installing.
+
+## Configuration Steps
+
+### Step 1: Verify the plugin is installed
+
+Check that the plugin exists:
+
+```bash
+ls ~/.openclaw/plugins/ppq-private-mode/
+```
+
+If the directory does not exist, stop and tell the user they need to install the plugin first (see Prerequisites above). Do not continue.
+
+### Step 2: Get the user's PPQ API key
+
+Ask the user for their PPQ.AI API key. They can find it at https://ppq.ai/api-docs -- it starts with `sk-`.
+
+Do not proceed until the user provides their key.
+
+### Step 3: Add the provider to OpenClaw config
+
+Merge the following into `~/.openclaw/openclaw.json`, preserving all existing settings.
+
+Add a new provider entry under `models.providers`:
+
+```json
+"ppq-private": {
+  "baseUrl": "http://127.0.0.1:8787/v1",
+  "apiKey": "unused",
+  "api": "openai-completions",
+  "models": [
+    { "id": "private/kimi-k2-5", "name": "private/kimi-k2-5" },
+    { "id": "private/deepseek-r1-0528", "name": "private/deepseek-r1-0528" },
+    { "id": "private/gpt-oss-120b", "name": "private/gpt-oss-120b" },
+    { "id": "private/llama3-3-70b", "name": "private/llama3-3-70b" },
+    { "id": "private/qwen3-vl-30b", "name": "private/qwen3-vl-30b" }
+  ]
+}
+```
+
+Add the plugin entry under `plugins.entries`:
+
+```json
+"ppq-private-mode": {
+  "config": {
+    "apiKey": "<the key the user provided>"
+  }
+}
+```
+
+### Step 4: Restart the gateway
+
+```bash
+systemctl --user restart openclaw-gateway.service
+```
+
+### Step 5: Confirm to the user
+
+Tell the user PPQ Private Mode is configured. Available encrypted models:
+
+- `private/kimi-k2-5` -- Fast general tasks
+- `private/deepseek-r1-0528` -- Reasoning and analysis
+- `private/gpt-oss-120b` -- Cost-efficient general use
+- `private/llama3-3-70b` -- Open-source tasks
+- `private/qwen3-vl-30b` -- Vision plus text
+
+Switch with: `openclaw models set private/kimi-k2-5`
+
+## About
+
+PPQ.AI provides pay-per-query AI with no subscriptions. Private models run inside hardware secure enclaves. Learn more at https://ppq.ai