@oked/openclaw 0.6.25 → 0.6.27

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -3,7 +3,21 @@
3
3
  [![npm version](https://img.shields.io/npm/v/@oked/openclaw.svg)](https://www.npmjs.com/package/@oked/openclaw)
4
4
  [![License: Apache-2.0](https://img.shields.io/npm/l/@oked/openclaw.svg)](./LICENSE)
5
5
 
6
- OKed pauses risky OpenClaw actions, like `rm -rf`, force-push, destructive SQL, and production deploys, until you approve them in Telegram or on the [web dashboard](https://oked.ai/dashboard). Reads and other ordinary actions just run. OKed is free during beta, and every decision gets a signed receipt. The iPhone app is coming soon.
6
+ OKed pauses risky OpenClaw actions, like `rm -rf`, force-push, destructive SQL, and production deploys, until you approve them in Telegram or on the [web dashboard](https://oked.ai/dashboard). Reads and other ordinary actions just run. Every decision gets a signed receipt.
7
+
8
+ ```bash
9
+ openclaw plugins install clawhub:@oked/openclaw
10
+ npx @oked/openclaw-cli init
11
+ ```
12
+
13
+ A non-interactive install needs `--accept-capabilities` so OpenClaw can record the capability consent:
14
+
15
+ ```bash
16
+ openclaw plugins install clawhub:@oked/openclaw --accept-capabilities
17
+ npx @oked/openclaw-cli init
18
+ ```
19
+
20
+ The install asks you to allow the Prompt injection capability. OKed asks for it because a denial returns the reason to the agent. That text is how the agent learns the action was blocked and should stop.
7
21
 
8
22
  A `before_tool_call` hook runs for every tool the host reports (built-in or registered by a skill) and classifies it. Calls at `review` and `high_stakes` wait until you decide. A denial returns `{ block: true, blockReason }`.
9
23
 
@@ -11,22 +25,19 @@ OpenClaw 2026.5.4 or newer is required. That release treats the returned denial
11
25
 
12
26
  ## Install
13
27
 
14
- Install from npm:
28
+ The two commands above install from [ClawHub](https://clawhub.ai/plugins/@oked/openclaw) and pair this machine. `npx @oked/openclaw-cli init` needs the `openclaw` command on your PATH. It pairs this device (or reuses an existing API key), sets `minTier` (a terminal prompt when none is set), adds `oked` to `plugins.allow`, writes `plugins.entries.oked` in `~/.openclaw/openclaw.json`, and offers to restart the gateway.
15
29
 
16
- ```bash
17
- openclaw plugins install npm:@oked/openclaw
18
- ```
30
+ On OpenClaw 2026.10.9 a package name with no source locator is an npm install. A noninteractive npm install stops with `Install cancelled; rerun with --force`. The `clawhub:` locator selects ClawHub.
19
31
 
20
- Once the package is listed on ClawHub, `openclaw plugins install @oked/openclaw` installs it from there.
21
-
22
- Pair this machine with [`@oked/openclaw-cli`](../openclaw-cli). The CLI needs the `openclaw` command on your PATH. It pairs this device (or reuses an existing API key), sets `minTier` (a terminal prompt when none is set), writes the entry into `~/.openclaw/openclaw.json`, and offers to restart the gateway.
32
+ To install the plugin straight from npm instead:
23
33
 
24
34
  ```bash
25
- npm install -g @oked/openclaw-cli
26
- oked-openclaw init
35
+ openclaw plugins install npm:@oked/openclaw
27
36
  ```
28
37
 
29
- If this package is not already installed, and there is no local checkout, `oked-openclaw init` tries `openclaw plugins install @oked/openclaw` (ClawHub). If that fails, it retries `openclaw plugins install npm:@oked/openclaw`. A checkout or a global npm copy is still linked with `openclaw plugins install --link`.
38
+ You can also install the CLI globally with `npm install -g @oked/openclaw-cli` and run `oked-openclaw init`.
39
+
40
+ If this package is not already installed, and there is no local checkout, `oked-openclaw init` tries `openclaw plugins install clawhub:@oked/openclaw` ([ClawHub](https://clawhub.ai/plugins/@oked/openclaw)). If that fails, it retries `openclaw plugins install npm:@oked/openclaw`. A checkout or a global npm copy is still linked with `openclaw plugins install --link`.
30
41
 
31
42
  To wire the config by hand after the plugin install, edit `~/.openclaw/openclaw.json`:
32
43
 
@@ -53,7 +64,7 @@ Keys live under `plugins.entries.oked`. The plugin manifest sets `additionalProp
53
64
 
54
65
  | Key | Type | Default | Description |
55
66
  |---|---|---|---|
56
- | `apiKey` | `string` | `OKED_API_KEY` env | OKed API key. Required. With no key, sensitive calls are denied. |
67
+ | `apiKey` | `string` | `OKED_API_KEY` env | OKed API key. With no key, the gateway starts pairing and sensitive calls are denied. |
57
68
  | `minTier` | `"safe" \| "warning" \| "review" \| "high_stakes"` | `"review"` | Lowest tier that can ask for approval. `warning` never blocks: only `review` and `high_stakes` do. Env `OKED_MIN_TIER` is the fallback when the config value is absent. |
58
69
  | `alwaysApprove` | `string[]` | `[]` | Tool names that are always `high_stakes`, whatever the classifier says. |
59
70
  | `alwaysAllow` | `string[]` | `[]` | Tool names that are always `safe`. Use sparingly. |
@@ -66,7 +77,7 @@ Names are matched against OpenClaw skill conventions, then unknown names default
66
77
 
67
78
  - **High stakes** (always an approval at the default `minTier`): names that send, post, publish, call, dial, charge, pay, delete, drop, deploy, or release, among the patterns in `src/classify-openclaw.ts`.
68
79
  - **Review** (an approval at the default `minTier`): `create`, `update`, `write`, `edit`, `rename`, `modify`, and any tool name the classifier does not recognize.
69
- - **Safe** (never gated): `get_*`, `list_*`, `search_*`, `read_*`, `find_*`, and the other read-style prefixes and suffixes in that file.
80
+ - **Safe** (never gated): exact read-only OpenClaw built-ins such as `read`, `ls`, `web_search`, `web_fetch`, and `memory_search` (the full list is in `src/classify-openclaw.ts`), plus `get_*`, `list_*`, `search_*`, `read_*`, `find_*`, and the other read-style prefixes and suffixes in that file. `write`, `edit`, and `apply_patch` stay at review.
70
81
  - **Bash / shell / exec**: deferred to the `@oked/sdk` shell classifier (`rm -rf`, `git push --force`, and the rest).
71
82
 
72
83
  `warning` is logged by the SDK classifier and does not block, even if you set `minTier` below `review`.
@@ -81,7 +92,7 @@ Each approval is one JSON request. These fields are in the body:
81
92
  | `description` | One-line summary built from the tool arguments. |
82
93
  | `tier` | `review` or `high_stakes`. |
83
94
  | `nonce` | A new id for this request, so an old receipt cannot approve a later call. |
84
- | `client` | This package and version, for example `@oked/openclaw@0.6.25`. |
95
+ | `client` | This package and version, for example `@oked/openclaw@0.6.27`. |
85
96
  | `metadata.tool_input` | The full tool arguments. |
86
97
  | `metadata.cwd` | Working directory of the OpenClaw process. |
87
98
  | `metadata.source` | `openclaw`. |
@@ -99,9 +110,24 @@ The signed receipt is bound to the action, description, tool input (including an
99
110
 
100
111
  To stop sending the excerpt, set `sendScriptContent` to `false` or export `OKED_SEND_SCRIPT_CONTENT=0`. The default is to send it.
101
112
 
113
+ ### Unpaired install
114
+
115
+ On the first gateway start with no API key, OKed sends one install request. The body has four fields:
116
+
117
+ | Field | Contents |
118
+ |---|---|
119
+ | `client_type` | `openclaw`. |
120
+ | `plugin_version` | This package's version, for example `0.6.27`. |
121
+ | `openclaw_version` | The OpenClaw version the gateway reports. `unknown` when the host does not provide one. |
122
+ | `install_id` | A random id stored in `~/.oked/openclaw-install.json` on this machine. |
123
+
124
+ The body contains only those fields. The same install id is sent once. Set `OKED_TELEMETRY=0` to skip the request. A failed request is ignored and retried on a later gateway start until one succeeds.
125
+
126
+ The gateway log also prints a pair link (`https://app.oked.ai/pair?code=...`) and the code. Sensitive calls stay denied until pairing finishes or you run `npx @oked/openclaw-cli init`. The denial text tells the agent to open that link or run that command.
127
+
102
128
  ## Degraded-mode behavior
103
129
 
104
- Explicit denials, invalid API keys, a missing API key, receipts that do not verify, and unexpected plugin errors deny the tool call. If OKed cannot be reached, the default is to deny `high_stakes` and allow lower tiers, so a short outage does not stop every workflow. Set `OKED_STRICT_FAIL_CLOSED=1` (or `true`) to deny every sensitive action during an outage. That is the recommended setting when these actions should stay blocked until you can decide.
130
+ Explicit denials, invalid API keys, a missing API key, receipts that do not verify, and unexpected plugin errors deny the tool call. A missing API key denies every sensitive call, including `review`. If OKed cannot be reached and a key is set, the default is to deny `high_stakes` and allow lower tiers, so a short outage does not stop every workflow. Set `OKED_STRICT_FAIL_CLOSED=1` (or `true`) to deny every sensitive action during an outage. That is the recommended setting when these actions should stay blocked until you can decide.
105
131
 
106
132
  ## Development
107
133
 
@@ -32,6 +32,41 @@ const SAFE_PATTERNS = [
32
32
  /_version$/,
33
33
  /_health$/,
34
34
  ];
35
+ /**
36
+ * Exact OpenClaw core tool ids that only read, list, search, or fetch.
37
+ * The match is case-insensitive and exact, so `read` is safe and
38
+ * `read_and_delete_file` is not. Names are from OpenClaw v2026.10.9
39
+ * `src/agents/tool-catalog.ts` (`CORE_TOOL_DEFINITIONS`). Session summaries
40
+ * are from `src/agents/tool-description-presets.ts` at the same tag.
41
+ *
42
+ * Not included: `glob`, `grep`, `find`, and `search` are not core tool ids
43
+ * in that catalog. `write`, `edit`, and `apply_patch` change files.
44
+ * `exec`, `bash`, and `shell` stay on the shell classifier.
45
+ */
46
+ const SAFE_BUILTIN_TOOLS = new Set([
47
+ // Files: "List directory entries", "Read file contents".
48
+ "ls",
49
+ "read",
50
+ // Web: "Search the web", "Fetch web content", "Search X posts".
51
+ "web_search",
52
+ "web_fetch",
53
+ "x_search",
54
+ // Memory: "Semantic search", "Read memory files".
55
+ "memory_search",
56
+ "memory_get",
57
+ // Sessions and agents that only list, read, or search.
58
+ "presence",
59
+ "sessions_list",
60
+ "sessions_history",
61
+ "sessions_search",
62
+ "conversations_list",
63
+ "session_status",
64
+ "github_identity_status",
65
+ "agents_list",
66
+ "get_goal",
67
+ "skills_search",
68
+ "skills_read",
69
+ ]);
35
70
  const HIGH_STAKES_PATTERNS = [
36
71
  // Communication that touches the real world
37
72
  /(_|^)(send|reply|post|publish|broadcast|email|sms|imessage|whatsapp|slack|telegram|tweet|toot)$/,
@@ -72,6 +107,8 @@ export function classifyOpenClawTool(toolName, toolInput, opts) {
72
107
  if (re.test(lower))
73
108
  return "high_stakes";
74
109
  }
110
+ if (SAFE_BUILTIN_TOOLS.has(lower))
111
+ return "safe";
75
112
  for (const re of SAFE_PATTERNS) {
76
113
  if (re.test(lower))
77
114
  return "safe";
package/dist/index.d.ts CHANGED
@@ -69,6 +69,10 @@ interface PluginLogger {
69
69
  interface OpenClawPluginApi {
70
70
  pluginConfig?: OkedPluginConfig;
71
71
  logger?: PluginLogger;
72
+ /** Present on a live gateway. Metadata-only registration may omit it or throw on access. */
73
+ runtime?: {
74
+ version?: string;
75
+ };
72
76
  on: (hookName: string, handler: (event: BeforeToolCallEvent, ctx: BeforeToolCallContext) => Promise<BeforeToolCallResult | void> | BeforeToolCallResult | void) => void;
73
77
  }
74
78
  /**
package/dist/index.js CHANGED
@@ -26,6 +26,8 @@ import * as path from "node:path";
26
26
  import { fileURLToPath } from "node:url";
27
27
  import { OKedClient, describe as describeAction, degradedDecision, OKedAuthError, OKedBackendUnreachableError, OKedReceiptError, TIER_ORDER, } from "@oked/sdk";
28
28
  import { classifyOpenClawTool } from "./classify-openclaw.js";
29
+ import { sendAnonymousInstallPing } from "./install-ping.js";
30
+ import { beginDevicePairing, persistPairedApiKey, unpairedDenyReason } from "./pairing.js";
29
31
  import { redactScriptExcerpt, resolveSendScriptContent, tryReadScriptFile } from "./script-excerpt.js";
30
32
  function tryStatRmTarget(command) {
31
33
  const m = command.trim().match(/\b(?:rm|trash|trash-put|rmdir)\s+(?:-[^\s]+\s+)*(['"]?)([^\s'"]+)\1/);
@@ -78,6 +80,24 @@ const CLIENT_ID = (() => {
78
80
  }
79
81
  })();
80
82
  const PLUGIN_ID = "oked";
83
+ function pluginVersion() {
84
+ const at = CLIENT_ID.lastIndexOf("@");
85
+ return at > 0 ? CLIENT_ID.slice(at + 1) : "0.0.0";
86
+ }
87
+ function readHostVersion(api) {
88
+ try {
89
+ const version = api.runtime?.version;
90
+ if (typeof version === "string" && version.trim())
91
+ return version.trim();
92
+ }
93
+ catch {
94
+ // Metadata-only registration has no runtime object.
95
+ }
96
+ const fromEnv = process.env.OPENCLAW_VERSION;
97
+ if (typeof fromEnv === "string" && fromEnv.trim())
98
+ return fromEnv.trim();
99
+ return "unknown";
100
+ }
81
101
  const LISTING_DESCRIPTION = "Pauses risky OpenClaw actions, like rm -rf, force-push, destructive SQL and prod deploys, until you approve them in Telegram or on the OKed web dashboard. Everything else just runs. Every decision gets a signed receipt.";
82
102
  const plugin = {
83
103
  id: PLUGIN_ID,
@@ -86,8 +106,8 @@ const plugin = {
86
106
  register(api) {
87
107
  const cfg = api.pluginConfig ?? {};
88
108
  const log = api.logger;
89
- const oked = new OKedClient({
90
- apiKey: cfg.apiKey ?? process.env.OKED_API_KEY,
109
+ const makeClient = (apiKey) => new OKedClient({
110
+ apiKey: apiKey ?? cfg.apiKey ?? process.env.OKED_API_KEY,
91
111
  backendUrl: cfg.backendUrl ?? process.env.OKED_BACKEND_URL,
92
112
  ...(cfg.timeoutMs ? { timeout: cfg.timeoutMs } : {}),
93
113
  ...(cfg.strictFailClosed !== undefined
@@ -96,9 +116,27 @@ const plugin = {
96
116
  client: CLIENT_ID,
97
117
  source: "openclaw",
98
118
  });
119
+ let oked = makeClient();
120
+ let pairing;
99
121
  if (!oked.apiKey) {
100
- log?.warn?.(`[oked] no apiKey configured. Plugin will fail-safe DENY every sensitive tool call. ` +
101
- `Set OKED_API_KEY env var or plugins.entries.oked.apiKey in openclaw.json.`);
122
+ pairing = beginDevicePairing({
123
+ backendUrl: oked.backendUrl,
124
+ clientVersion: pluginVersion(),
125
+ hostname: os.hostname(),
126
+ log: (line) => log?.warn?.(line),
127
+ onApproved: (apiKey) => {
128
+ oked = makeClient(apiKey);
129
+ const saved = persistPairedApiKey(apiKey, oked.backendUrl);
130
+ if (!saved.savedOkedConfig) {
131
+ log?.error?.("[oked] Paired. The key is active for this gateway run. Saving ~/.oked/config.json failed.");
132
+ }
133
+ },
134
+ });
135
+ void sendAnonymousInstallPing({
136
+ backendUrl: oked.backendUrl,
137
+ pluginVersion: pluginVersion(),
138
+ openclawVersion: readHostVersion(api),
139
+ }).catch(() => { });
102
140
  }
103
141
  // minTier resolution order: openclaw.json > OKED_MIN_TIER env var > default.
104
142
  // (The env-var fallback exists because some OpenClaw versions reject
@@ -153,6 +191,15 @@ const plugin = {
153
191
  if (TIER_ORDER[tier] < minTierLevel || !APPROVAL_TIERS.has(tier)) {
154
192
  return; // void = allow
155
193
  }
194
+ // No key: deny. Do not call approve(), which would treat a dead backend
195
+ // as an outage and allow review-tier calls. Wait briefly so the reason
196
+ // can include the pair URL from the one pairing attempt started above.
197
+ if (!oked.apiKey && pairing) {
198
+ await pairing.ready;
199
+ }
200
+ if (!oked.apiKey) {
201
+ return deny(unpairedDenyReason(pairing?.state ?? { phase: "unavailable" }));
202
+ }
156
203
  // Sensitive. Ask the human.
157
204
  const description = describeAction(toolName, params);
158
205
  log?.info?.(`[oked] requesting approval: tool=${toolName} tier=${tier} session=${ctx.sessionKey ?? ctx.sessionId ?? "?"}`);
@@ -0,0 +1,34 @@
1
+ /**
2
+ * Anonymous install ping for an unpaired OpenClaw gateway.
3
+ *
4
+ * One request per install id, on the first gateway start that has no API key.
5
+ * The body is only client_type, plugin version, OpenClaw version, and a random
6
+ * id stored on this machine. No hostname, no API key, no tool arguments.
7
+ * OKED_TELEMETRY=0 skips the request. Failures are silent.
8
+ *
9
+ * The backend endpoint is POST /api/v1/install. This repo does not contain the
10
+ * backend. The client sends the payload below and ignores the response except
11
+ * for the HTTP status.
12
+ */
13
+ export declare const INSTALL_PING_PATH = "/api/v1/install";
14
+ export interface InstallPingPayload {
15
+ client_type: "openclaw";
16
+ plugin_version: string;
17
+ openclaw_version: string;
18
+ install_id: string;
19
+ }
20
+ export declare function telemetryEnabled(env?: NodeJS.ProcessEnv): boolean;
21
+ export declare function defaultInstallStateFile(home?: string): string;
22
+ /**
23
+ * Send the anonymous install ping once for this install id.
24
+ * Returns the payload when a request was attempted, otherwise undefined.
25
+ * Never throws.
26
+ */
27
+ export declare function sendAnonymousInstallPing(opts: {
28
+ backendUrl: string;
29
+ pluginVersion: string;
30
+ openclawVersion: string;
31
+ stateFile?: string;
32
+ fetchImpl?: typeof fetch;
33
+ env?: NodeJS.ProcessEnv;
34
+ }): Promise<InstallPingPayload | undefined>;
@@ -0,0 +1,101 @@
1
+ /**
2
+ * Anonymous install ping for an unpaired OpenClaw gateway.
3
+ *
4
+ * One request per install id, on the first gateway start that has no API key.
5
+ * The body is only client_type, plugin version, OpenClaw version, and a random
6
+ * id stored on this machine. No hostname, no API key, no tool arguments.
7
+ * OKED_TELEMETRY=0 skips the request. Failures are silent.
8
+ *
9
+ * The backend endpoint is POST /api/v1/install. This repo does not contain the
10
+ * backend. The client sends the payload below and ignores the response except
11
+ * for the HTTP status.
12
+ */
13
+ import { randomUUID } from "node:crypto";
14
+ import { chmodSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
15
+ import { homedir } from "node:os";
16
+ import path from "node:path";
17
+ export const INSTALL_PING_PATH = "/api/v1/install";
18
+ export function telemetryEnabled(env = process.env) {
19
+ const raw = env.OKED_TELEMETRY;
20
+ if (raw === undefined)
21
+ return true;
22
+ const value = raw.trim().toLowerCase();
23
+ return value !== "0" && value !== "false" && value !== "off" && value !== "no";
24
+ }
25
+ export function defaultInstallStateFile(home = homedir()) {
26
+ return path.join(home, ".oked", "openclaw-install.json");
27
+ }
28
+ function readState(file) {
29
+ try {
30
+ const parsed = JSON.parse(readFileSync(file, "utf8"));
31
+ if (!parsed || typeof parsed.installId !== "string" || !parsed.installId)
32
+ return undefined;
33
+ const state = { installId: parsed.installId };
34
+ if (typeof parsed.sentAt === "string" && parsed.sentAt)
35
+ state.sentAt = parsed.sentAt;
36
+ return state;
37
+ }
38
+ catch {
39
+ return undefined;
40
+ }
41
+ }
42
+ function writeState(file, state) {
43
+ mkdirSync(path.dirname(file), { recursive: true });
44
+ const payload = { installId: state.installId };
45
+ if (state.sentAt)
46
+ payload.sentAt = state.sentAt;
47
+ writeFileSync(file, JSON.stringify(payload, null, 2) + "\n", "utf8");
48
+ try {
49
+ chmodSync(file, 0o600);
50
+ }
51
+ catch {
52
+ // Windows does not honor this mode. The file stays in the user profile.
53
+ }
54
+ }
55
+ /**
56
+ * Send the anonymous install ping once for this install id.
57
+ * Returns the payload when a request was attempted, otherwise undefined.
58
+ * Never throws.
59
+ */
60
+ export async function sendAnonymousInstallPing(opts) {
61
+ try {
62
+ if (!telemetryEnabled(opts.env ?? process.env))
63
+ return undefined;
64
+ const stateFile = opts.stateFile ?? defaultInstallStateFile();
65
+ const existing = readState(stateFile);
66
+ if (existing?.sentAt)
67
+ return undefined;
68
+ const state = { installId: existing?.installId || randomUUID() };
69
+ const payload = {
70
+ client_type: "openclaw",
71
+ plugin_version: opts.pluginVersion,
72
+ openclaw_version: opts.openclawVersion || "unknown",
73
+ install_id: state.installId,
74
+ };
75
+ try {
76
+ writeState(stateFile, state);
77
+ }
78
+ catch {
79
+ // A missing state file means a later start may generate a new id.
80
+ }
81
+ const base = opts.backendUrl.replace(/\/$/, "");
82
+ const res = await (opts.fetchImpl ?? fetch)(`${base}${INSTALL_PING_PATH}`, {
83
+ method: "POST",
84
+ headers: { "Content-Type": "application/json" },
85
+ body: JSON.stringify(payload),
86
+ signal: AbortSignal.timeout(3000),
87
+ });
88
+ if (res.ok) {
89
+ try {
90
+ writeState(stateFile, { ...state, sentAt: new Date().toISOString() });
91
+ }
92
+ catch {
93
+ // The request landed. A later start may send the same id once more.
94
+ }
95
+ }
96
+ return payload;
97
+ }
98
+ catch {
99
+ return undefined;
100
+ }
101
+ }
@@ -0,0 +1,47 @@
1
+ /**
2
+ * Device-code pairing for a gateway that has no API key.
3
+ *
4
+ * Same endpoints as `oked-openclaw init`: POST /api/v1/device/code, then
5
+ * POST /api/v1/device/poll. One attempt per gateway start. The code is reused
6
+ * until it expires. A completed pairing is handed to onApproved, which saves
7
+ * the key the same way init does.
8
+ */
9
+ export interface PairingState {
10
+ phase: "starting" | "pending" | "approved" | "expired" | "unavailable";
11
+ userCode?: string;
12
+ pairUrl?: string;
13
+ apiKey?: string;
14
+ }
15
+ export interface PairingSession {
16
+ state: PairingState;
17
+ /** Resolves when the pair URL is known, or when starting pairing failed. */
18
+ ready: Promise<void>;
19
+ /** Resolves when this attempt finishes (approved, expired, or unavailable). */
20
+ settled: Promise<void>;
21
+ }
22
+ export declare function unpairedDenyReason(state: PairingState): string;
23
+ export declare function okedConfigPath(home?: string): string;
24
+ export declare function openclawConfigPath(home?: string): string;
25
+ /**
26
+ * Save a paired key the same way `oked-openclaw init` does:
27
+ * ~/.oked/config.json, plus plugins.allow and plugins.entries.oked in
28
+ * ~/.openclaw/openclaw.json. Never throws.
29
+ */
30
+ export declare function persistPairedApiKey(apiKey: string, backendUrl: string, home?: string): {
31
+ savedOkedConfig: boolean;
32
+ savedOpenClawConfig: boolean;
33
+ };
34
+ /**
35
+ * Start device pairing once. Call this once per gateway start.
36
+ * pollIntervalMs overrides the server interval (tests). Production omits it
37
+ * and waits the server interval, at least one second.
38
+ */
39
+ export declare function beginDevicePairing(opts: {
40
+ backendUrl: string;
41
+ clientVersion: string;
42
+ hostname: string;
43
+ log: (line: string) => void;
44
+ onApproved: (apiKey: string) => void;
45
+ fetchImpl?: typeof fetch;
46
+ pollIntervalMs?: number;
47
+ }): PairingSession;
@@ -0,0 +1,248 @@
1
+ /**
2
+ * Device-code pairing for a gateway that has no API key.
3
+ *
4
+ * Same endpoints as `oked-openclaw init`: POST /api/v1/device/code, then
5
+ * POST /api/v1/device/poll. One attempt per gateway start. The code is reused
6
+ * until it expires. A completed pairing is handed to onApproved, which saves
7
+ * the key the same way init does.
8
+ */
9
+ import { chmodSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
10
+ import { homedir } from "node:os";
11
+ import path from "node:path";
12
+ function delay(ms) {
13
+ return new Promise((resolve) => {
14
+ const timer = setTimeout(resolve, ms);
15
+ // The gateway stays up for other reasons. A poll timer must not keep a
16
+ // short-lived process alive after the last real handle closes.
17
+ timer.unref?.();
18
+ });
19
+ }
20
+ export function unpairedDenyReason(state) {
21
+ const cli = "run `npx @oked/openclaw-cli init`";
22
+ let how;
23
+ if (state.phase === "expired") {
24
+ how = `The pair code expired. ${cli}`;
25
+ }
26
+ else if (state.pairUrl && state.userCode) {
27
+ how = `Open ${state.pairUrl} (code ${state.userCode}) or ${cli}`;
28
+ }
29
+ else if (state.pairUrl) {
30
+ how = `Open ${state.pairUrl} or ${cli}`;
31
+ }
32
+ else {
33
+ how = `Open the pair link from the gateway log or ${cli}`;
34
+ }
35
+ return (`OKed is not set up yet. ${how}. ` +
36
+ `This action is denied until OKed is paired. ` +
37
+ `Do NOT retry the same action. Stop and ask the user to finish setup.`);
38
+ }
39
+ export function okedConfigPath(home = homedir()) {
40
+ return path.join(home, ".oked", "config.json");
41
+ }
42
+ export function openclawConfigPath(home = homedir()) {
43
+ return path.join(home, ".openclaw", "openclaw.json");
44
+ }
45
+ function readObject(file) {
46
+ try {
47
+ const parsed = JSON.parse(readFileSync(file, "utf8"));
48
+ if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
49
+ return { value: parsed, writable: true };
50
+ }
51
+ return { value: {}, writable: false };
52
+ }
53
+ catch (err) {
54
+ const missing = err.code === "ENOENT";
55
+ return { value: {}, writable: missing };
56
+ }
57
+ }
58
+ function writeJson(file, value) {
59
+ mkdirSync(path.dirname(file), { recursive: true });
60
+ writeFileSync(file, JSON.stringify(value, null, 2) + "\n", "utf8");
61
+ try {
62
+ chmodSync(file, 0o600);
63
+ }
64
+ catch {
65
+ // Windows does not honor this mode. The file stays in the user profile.
66
+ }
67
+ }
68
+ /**
69
+ * Save a paired key the same way `oked-openclaw init` does:
70
+ * ~/.oked/config.json, plus plugins.allow and plugins.entries.oked in
71
+ * ~/.openclaw/openclaw.json. Never throws.
72
+ */
73
+ export function persistPairedApiKey(apiKey, backendUrl, home = homedir()) {
74
+ const result = { savedOkedConfig: false, savedOpenClawConfig: false };
75
+ try {
76
+ const okedFile = okedConfigPath(home);
77
+ let existing = {};
78
+ try {
79
+ const parsed = JSON.parse(readFileSync(okedFile, "utf8"));
80
+ if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
81
+ existing = parsed;
82
+ }
83
+ }
84
+ catch {
85
+ existing = {};
86
+ }
87
+ writeJson(okedFile, { ...existing, apiKey, backendUrl });
88
+ result.savedOkedConfig = true;
89
+ }
90
+ catch {
91
+ result.savedOkedConfig = false;
92
+ }
93
+ try {
94
+ const openclawFile = openclawConfigPath(home);
95
+ const loaded = readObject(openclawFile);
96
+ if (!loaded.writable)
97
+ return result;
98
+ const cfg = loaded.value;
99
+ const plugins = cfg.plugins && typeof cfg.plugins === "object" && !Array.isArray(cfg.plugins)
100
+ ? cfg.plugins
101
+ : {};
102
+ const allow = Array.isArray(plugins.allow) ? [...plugins.allow] : [];
103
+ if (!allow.includes("oked"))
104
+ allow.push("oked");
105
+ plugins.allow = allow;
106
+ const entries = plugins.entries && typeof plugins.entries === "object" && !Array.isArray(plugins.entries)
107
+ ? plugins.entries
108
+ : {};
109
+ const prev = entries.oked && typeof entries.oked === "object" && !Array.isArray(entries.oked)
110
+ ? entries.oked
111
+ : {};
112
+ entries.oked = { ...prev, enabled: true, apiKey, backendUrl };
113
+ plugins.entries = entries;
114
+ cfg.plugins = plugins;
115
+ writeJson(openclawFile, cfg);
116
+ result.savedOpenClawConfig = true;
117
+ }
118
+ catch {
119
+ result.savedOpenClawConfig = false;
120
+ }
121
+ return result;
122
+ }
123
+ function pairUrlFromCode(code, userCode) {
124
+ if (typeof code.verification_uri_complete === "string" && code.verification_uri_complete) {
125
+ return code.verification_uri_complete;
126
+ }
127
+ return `https://app.oked.ai/pair?code=${encodeURIComponent(userCode)}`;
128
+ }
129
+ /**
130
+ * Start device pairing once. Call this once per gateway start.
131
+ * pollIntervalMs overrides the server interval (tests). Production omits it
132
+ * and waits the server interval, at least one second.
133
+ */
134
+ export function beginDevicePairing(opts) {
135
+ const state = { phase: "starting" };
136
+ const fetchImpl = opts.fetchImpl ?? fetch;
137
+ const base = opts.backendUrl.replace(/\/$/, "");
138
+ let resolveReady = () => { };
139
+ let resolveSettled = () => { };
140
+ const ready = new Promise((resolve) => {
141
+ resolveReady = resolve;
142
+ });
143
+ const settled = new Promise((resolve) => {
144
+ resolveSettled = resolve;
145
+ });
146
+ const finishReady = () => resolveReady();
147
+ const finishSettled = () => {
148
+ finishReady();
149
+ resolveSettled();
150
+ };
151
+ const poll = async (deviceCode, intervalSec, expiresSec) => {
152
+ const deadline = Date.now() + expiresSec * 1000;
153
+ const intervalMs = opts.pollIntervalMs !== undefined ? opts.pollIntervalMs : Math.max(1, intervalSec || 3) * 1000;
154
+ while (Date.now() < deadline && state.phase === "pending") {
155
+ await delay(intervalMs);
156
+ if (state.phase !== "pending")
157
+ return;
158
+ let pollRes;
159
+ try {
160
+ pollRes = await fetchImpl(`${base}/api/v1/device/poll`, {
161
+ method: "POST",
162
+ headers: { "Content-Type": "application/json" },
163
+ body: JSON.stringify({ device_code: deviceCode }),
164
+ signal: AbortSignal.timeout(10000),
165
+ });
166
+ }
167
+ catch {
168
+ continue;
169
+ }
170
+ if (pollRes.status === 410) {
171
+ state.phase = "expired";
172
+ opts.log("[oked] Pairing code expired. Run `npx @oked/openclaw-cli init`.");
173
+ return;
174
+ }
175
+ if (!pollRes.ok)
176
+ continue;
177
+ let body;
178
+ try {
179
+ body = (await pollRes.json());
180
+ }
181
+ catch {
182
+ continue;
183
+ }
184
+ if (body.status === "approved" && typeof body.api_key === "string" && body.api_key) {
185
+ state.phase = "approved";
186
+ state.apiKey = body.api_key;
187
+ try {
188
+ opts.onApproved(body.api_key);
189
+ }
190
+ catch {
191
+ // The key is still on state.apiKey for this process.
192
+ }
193
+ opts.log("[oked] Paired. This gateway will use the new API key.");
194
+ return;
195
+ }
196
+ }
197
+ if (state.phase === "pending") {
198
+ state.phase = "expired";
199
+ opts.log("[oked] Pairing timed out. Run `npx @oked/openclaw-cli init`.");
200
+ }
201
+ };
202
+ void (async () => {
203
+ try {
204
+ const res = await fetchImpl(`${base}/api/v1/device/code`, {
205
+ method: "POST",
206
+ headers: { "Content-Type": "application/json" },
207
+ body: JSON.stringify({
208
+ client_type: "openclaw",
209
+ hostname: opts.hostname,
210
+ client_version: opts.clientVersion,
211
+ }),
212
+ signal: AbortSignal.timeout(5000),
213
+ });
214
+ if (!res.ok) {
215
+ state.phase = "unavailable";
216
+ opts.log(`[oked] OKed is not set up yet. Pairing did not start (${res.status}). ` +
217
+ "Run `npx @oked/openclaw-cli init`. Sensitive tool calls are denied until then.");
218
+ finishSettled();
219
+ return;
220
+ }
221
+ const code = (await res.json());
222
+ if (typeof code.device_code !== "string" || typeof code.user_code !== "string" || !code.user_code) {
223
+ state.phase = "unavailable";
224
+ opts.log("[oked] OKed is not set up yet. Pairing did not start. " +
225
+ "Run `npx @oked/openclaw-cli init`. Sensitive tool calls are denied until then.");
226
+ finishSettled();
227
+ return;
228
+ }
229
+ state.phase = "pending";
230
+ state.userCode = code.user_code;
231
+ state.pairUrl = pairUrlFromCode(code, code.user_code);
232
+ opts.log(`[oked] OKed is not set up yet. Open ${state.pairUrl} (code ${state.userCode}) ` +
233
+ "or run `npx @oked/openclaw-cli init`. Sensitive tool calls are denied until pairing finishes.");
234
+ finishReady();
235
+ const interval = typeof code.interval === "number" ? code.interval : 3;
236
+ const expires = typeof code.expires_in === "number" ? code.expires_in : 600;
237
+ await poll(code.device_code, interval, expires);
238
+ finishSettled();
239
+ }
240
+ catch {
241
+ state.phase = "unavailable";
242
+ opts.log("[oked] OKed is not set up yet. Pairing did not start. " +
243
+ "Run `npx @oked/openclaw-cli init`. Sensitive tool calls are denied until then.");
244
+ finishSettled();
245
+ }
246
+ })();
247
+ return { state, ready, settled };
248
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@oked/openclaw",
3
- "version": "0.6.25",
3
+ "version": "0.6.27",
4
4
  "description": "Pauses risky OpenClaw actions, like rm -rf, force-push, destructive SQL and prod deploys, until you approve them in Telegram or on the OKed web dashboard. Everything else just runs. Every decision gets a signed receipt.",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",
@@ -21,7 +21,7 @@
21
21
  "prebuild": "npm run build --workspace=@oked/sdk",
22
22
  "build": "tsc",
23
23
  "dev": "tsc --watch",
24
- "test": "npm run build && node src/clawhub-metadata.test.mjs && node src/script-excerpt.test.mjs && node src/smoke.test.mjs",
24
+ "test": "npm run build && node src/classify-openclaw.test.mjs && node src/clawhub-metadata.test.mjs && node src/script-excerpt.test.mjs && node src/install-ping.test.mjs && node src/pairing.test.mjs && node src/smoke.test.mjs",
25
25
  "prepublishOnly": "npm run build"
26
26
  },
27
27
  "openclaw": {
@@ -51,7 +51,7 @@
51
51
  }
52
52
  },
53
53
  "dependencies": {
54
- "@oked/sdk": "0.6.25"
54
+ "@oked/sdk": "0.6.27"
55
55
  },
56
56
  "devDependencies": {
57
57
  "@types/node": "^26.6.5",