openclaw-airlock 0.4.7

package/dist/index.js

@@ -0,0 +1,88 @@
+/**
+ * Airlock Plugin for OpenClaw — Entry Point
+ *
+ * Registers all Airlock capabilities with the OpenClaw plugin system:
+ * - Config validation
+ * - Pairing state restoration from disk
+ * - Presence heartbeat
+ * - requestApproval tool (AI-callable)
+ * - checkStatus tool (AI-callable)
+ * - beforeTool hook (automatic enforcement with DND check)
+ * - /airlock-status command (diagnostics)
+ * - airlock setup CLI command
+ * - airlock pair CLI command
+ */
+import { loadAndValidateConfig } from "./config.js";
+import { createAirlockClient } from "./client.js";
+import { registerRequestApprovalTool } from "./tools/requestApproval.js";
+import { registerCheckStatusTool } from "./tools/checkStatus.js";
+import { registerBeforeToolHook } from "./hooks/beforeTool.js";
+import { registerAirlockStatusCommand } from "./commands/airlockStatus.js";
+import { registerCliCommands } from "./cli/register.js";
+/**
+ * Stub for OpenClaw's definePluginEntry.
+ * Replace with actual import when the SDK is available:
+ *   import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
+ */
+function definePluginEntry(def) {
+    return def;
+}
+// ── Plugin Definition ───────────────────────────────────────────
+export default definePluginEntry({
+    id: "openclaw-airlock",
+    name: "Airlock Security Gateway",
+    description: "Enforces human-in-the-loop approval for risky AI actions via Airlock Gateway. " +
+        "Supports tool-based and hook-based enforcement with polling-based decision handling.",
+    register(api) {
+        // AIRLOCK_COMPAT_SHIM v7
+        if (!api.getConfig) {
+            api.getConfig = () => api.pluginConfig ?? {};
+        }
+        const _oCmd = api.registerCommand;
+        if (_oCmd) {
+            api.registerCommand = function (a, b) {
+                if (typeof b === "function") {
+                    return _oCmd.call(api, Object.assign({}, a, { handler: b }));
+                }
+                return _oCmd.call(api, a);
+            };
+        }
+        // Hook shim removed — using correct OpenClaw API: registerHook(event, handler, { name, description })
+        // END AIRLOCK_COMPAT_SHIM
+        const readyApi = api;
+        // Phase 2: Config
+        let config;
+        try {
+            config = loadAndValidateConfig(readyApi.getConfig());
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.error(`[Airlock] Plugin disabled — config error: ${msg}`);
+            return;
+        }
+        // Phase 3: Client
+        const client = createAirlockClient(config);
+        // Restore pairing state from disk + start presence heartbeat
+        // (async — non-blocking; plugin is usable immediately if state exists in config)
+        client.initialize().catch((err) => {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.warn(`[Airlock] Initialization warning: ${msg}`);
+        });
+        // Phase 4: Tool — requestApproval
+        registerRequestApprovalTool(readyApi, client, config);
+        // Phase 5: Tool — checkStatus
+        registerCheckStatusTool(readyApi, client, config);
+        // Phase 6: Hook — beforeTool (with DND check)
+        registerBeforeToolHook(readyApi, client, config);
+        // Phase 7: Command — /airlock-status
+        registerAirlockStatusCommand(readyApi, client, config);
+        // Phase 8: CLI commands — single registrar for all airlock subcommands
+        registerCliCommands(readyApi, client, config);
+        console.info(`[Airlock] Plugin loaded — enforcer=${config.enforcerId}, ` +
+            `failMode=${config.failMode}, ` +
+            `protectedTools=${config.protectedTools.length > 0 ? config.protectedTools.join(",") : "(none)"}`);
+    },
+});
+export { loadAndValidateConfig, ConfigError } from "./config.js";
+export { createAirlockClient } from "./client.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/state.d.ts

@@ -0,0 +1,44 @@
+/**
+ * State persistence for pairing results.
+ *
+ * After a successful pairing claim, we need to persist:
+ * - routingToken (used in artifact metadata for routing to approver)
+ * - encryptionKey (AES-256-GCM key for artifact encryption)
+ * - pairedKeys (Ed25519 public keys for decision signature verification)
+ *
+ * State is stored as a JSON file in the working directory.
+ * This is similar to the Claude Code enforcer's config.storeRoutingTokenAsync() pattern.
+ */
+import type { PairedKeyEntry } from "./crypto.js";
+export interface AirlockPairingState {
+    /** Routing token from completed pairing. */
+    routingToken: string;
+    /** AES-256-GCM encryption key (base64url) derived via X25519 ECDH. */
+    encryptionKey: string;
+    /** Paired approver public keys, keyed by signerKeyId. */
+    pairedKeys: Record<string, PairedKeyEntry>;
+    /** Timestamp of when pairing was completed. */
+    pairedAt: string;
+    /** The pairing nonce used. */
+    pairingNonce: string;
+}
+/**
+ * Load persisted pairing state from disk.
+ * Returns null if no state file exists or it's corrupted.
+ */
+export declare function loadPairingState(): Promise<AirlockPairingState | null>;
+/**
+ * Save pairing state to disk.
+ * Creates the .airlock directory if it doesn't exist.
+ */
+export declare function savePairingState(state: AirlockPairingState): Promise<void>;
+/**
+ * Clear persisted pairing state (e.g. on pairing revocation).
+ */
+export declare function clearPairingState(): Promise<void>;
+/**
+ * Get paired keys from persisted state.
+ * Returns an empty record if no state is available.
+ */
+export declare function loadPairedKeys(): Promise<Record<string, PairedKeyEntry>>;
+//# sourceMappingURL=state.d.ts.map

package/dist/state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../src/state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAIlD,MAAM,WAAW,mBAAmB;IAClC,4CAA4C;IAC5C,YAAY,EAAE,MAAM,CAAC;IACrB,sEAAsE;IACtE,aAAa,EAAE,MAAM,CAAC;IACtB,yDAAyD;IACzD,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IAC3C,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,CAAC;IACjB,8BAA8B;IAC9B,YAAY,EAAE,MAAM,CAAC;CACtB;AAsBD;;;GAGG;AACH,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC,CAc5E;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAMhF;AAED;;GAEG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC,CAOvD;AAED;;;GAGG;AACH,wBAAsB,cAAc,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,CAG9E"}

package/dist/state.js

@@ -0,0 +1,79 @@
+/**
+ * State persistence for pairing results.
+ *
+ * After a successful pairing claim, we need to persist:
+ * - routingToken (used in artifact metadata for routing to approver)
+ * - encryptionKey (AES-256-GCM key for artifact encryption)
+ * - pairedKeys (Ed25519 public keys for decision signature verification)
+ *
+ * State is stored as a JSON file in the working directory.
+ * This is similar to the Claude Code enforcer's config.storeRoutingTokenAsync() pattern.
+ */
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import { homedir } from "node:os";
+// ── Constants ───────────────────────────────────────────────────
+const OPENCLAW_DIR = ".openclaw";
+const STATE_DIR = ".airlock";
+const STATE_FILE = "pairing-state.json";
+// ── State Operations ────────────────────────────────────────────
+/**
+ * Returns a stable state file path: ~/.openclaw/.airlock/pairing-state.json
+ *
+ * Uses homedir() instead of process.cwd() so the pairing state is found
+ * regardless of which user or working directory runs the CLI command.
+ * Falls back to OPENCLAW_HOME env var if set.
+ */
+function getStatePath() {
+    const base = process.env.OPENCLAW_HOME ?? join(homedir(), OPENCLAW_DIR);
+    return join(base, STATE_DIR, STATE_FILE);
+}
+/**
+ * Load persisted pairing state from disk.
+ * Returns null if no state file exists or it's corrupted.
+ */
+export async function loadPairingState() {
+    try {
+        const raw = await readFile(getStatePath(), "utf-8");
+        const state = JSON.parse(raw);
+        // Basic validation
+        if (!state.routingToken || !state.encryptionKey) {
+            return null;
+        }
+        return state;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Save pairing state to disk.
+ * Creates the .airlock directory if it doesn't exist.
+ */
+export async function savePairingState(state) {
+    const statePath = getStatePath();
+    const dir = dirname(statePath);
+    await mkdir(dir, { recursive: true });
+    await writeFile(statePath, JSON.stringify(state, null, 2), "utf-8");
+}
+/**
+ * Clear persisted pairing state (e.g. on pairing revocation).
+ */
+export async function clearPairingState() {
+    try {
+        const { unlink } = await import("node:fs/promises");
+        await unlink(getStatePath());
+    }
+    catch {
+        // File might not exist, that's fine
+    }
+}
+/**
+ * Get paired keys from persisted state.
+ * Returns an empty record if no state is available.
+ */
+export async function loadPairedKeys() {
+    const state = await loadPairingState();
+    return state?.pairedKeys ?? {};
+}
+//# sourceMappingURL=state.js.map

package/dist/state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../src/state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAC9D,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAkBlC,mEAAmE;AAEnE,MAAM,YAAY,GAAG,WAAW,CAAC;AACjC,MAAM,SAAS,GAAG,UAAU,CAAC;AAC7B,MAAM,UAAU,GAAG,oBAAoB,CAAC;AAExC,mEAAmE;AAEnE;;;;;;GAMG;AACH,SAAS,YAAY;IACnB,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,aAAa,IAAI,IAAI,CAAC,OAAO,EAAE,EAAE,YAAY,CAAC,CAAC;IACxE,OAAO,IAAI,CAAC,IAAI,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC;AAC3C,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB;IACpC,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,YAAY,EAAE,EAAE,OAAO,CAAC,CAAC;QACpD,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAwB,CAAC;QAErD,mBAAmB;QACnB,IAAI,CAAC,KAAK,CAAC,YAAY,IAAI,CAAC,KAAK,CAAC,aAAa,EAAE,CAAC;YAChD,OAAO,IAAI,CAAC;QACd,CAAC;QAED,OAAO,KAAK,CAAC;IACf,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,KAA0B;IAC/D,MAAM,SAAS,GAAG,YAAY,EAAE,CAAC;IACjC,MAAM,GAAG,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IAE/B,MAAM,KAAK,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACtC,MAAM,SAAS,CAAC,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;AACtE,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB;IACrC,IAAI,CAAC;QACH,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,MAAM,CAAC,kBAAkB,CAAC,CAAC;QACpD,MAAM,MAAM,CAAC,YAAY,EAAE,CAAC,CAAC;IAC/B,CAAC;IAAC,MAAM,CAAC;QACP,oCAAoC;IACtC,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc;IAClC,MAAM,KAAK,GAAG,MAAM,gBAAgB,EAAE,CAAC;IACvC,OAAO,KAAK,EAAE,UAAU,IAAI,EAAE,CAAC;AACjC,CAAC"}

package/dist/tools/checkStatus.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Tool: checkStatus — AI-callable tool to check an existing exchange status.
+ *
+ * The agent can use this to follow up on a previously submitted approval
+ * request and check whether a decision has been made.
+ */
+import type { AirlockClient } from "../client.js";
+import type { AirlockConfig } from "../config.js";
+/** Input schema for the checkStatus tool. */
+export interface CheckStatusInput {
+    /** The exchange request ID from a previous approval request. */
+    requestId: string;
+}
+/** Output schema for the checkStatus tool. */
+export interface CheckStatusOutput {
+    /** The exchange state (e.g. "Pending", "Decided", "Expired", "Withdrawn"). */
+    state: string;
+    /** Human-readable message. */
+    message: string;
+}
+/** Tool definition for OpenClaw registration. */
+export declare const checkStatusToolDef: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        required: readonly ["requestId"];
+        properties: {
+            requestId: {
+                type: "string";
+                description: string;
+            };
+        };
+    };
+};
+/**
+ * Register the checkStatus tool with the OpenClaw plugin API.
+ */
+export declare function registerCheckStatusTool(api: {
+    registerTool: (def: unknown, handler: (input: unknown) => Promise<unknown>) => void;
+}, client: AirlockClient, _config: AirlockConfig): void;
+//# sourceMappingURL=checkStatus.d.ts.map

package/dist/tools/checkStatus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkStatus.d.ts","sourceRoot":"","sources":["../../src/tools/checkStatus.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,6CAA6C;AAC7C,MAAM,WAAW,gBAAgB;IAC/B,gEAAgE;IAChE,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,8CAA8C;AAC9C,MAAM,WAAW,iBAAiB;IAChC,8EAA8E;IAC9E,KAAK,EAAE,MAAM,CAAC;IACd,8BAA8B;IAC9B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,iDAAiD;AACjD,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;CAe9B,CAAC;AAEF;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,EAAE;IAAE,YAAY,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,KAAK,IAAI,CAAA;CAAE,EAC5F,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,aAAa,GACrB,IAAI,CAyCN"}

package/dist/tools/checkStatus.js

@@ -0,0 +1,67 @@
+/**
+ * Tool: checkStatus — AI-callable tool to check an existing exchange status.
+ *
+ * The agent can use this to follow up on a previously submitted approval
+ * request and check whether a decision has been made.
+ */
+import { AirlockGatewayError } from "@airlockapp/gateway-sdk";
+/** Tool definition for OpenClaw registration. */
+export const checkStatusToolDef = {
+    name: "airlock_check_status",
+    description: "Check the status of a previously submitted Airlock approval request. " +
+        "Use the requestId returned from airlock_request_approval.",
+    inputSchema: {
+        type: "object",
+        required: ["requestId"],
+        properties: {
+            requestId: {
+                type: "string",
+                description: "The exchange request ID from a previous approval request",
+            },
+        },
+    },
+};
+/**
+ * Register the checkStatus tool with the OpenClaw plugin API.
+ */
+export function registerCheckStatusTool(api, client, _config) {
+    api.registerTool(checkStatusToolDef, async (rawInput) => {
+        const input = rawInput;
+        if (!input.requestId?.trim()) {
+            return {
+                state: "error",
+                message: "requestId is required",
+            };
+        }
+        try {
+            const status = await client.getExchangeStatus(input.requestId);
+            let message = `Exchange ${input.requestId}: ${status.state}`;
+            if (status.state === "Decided") {
+                message += " — a decision has been made.";
+            }
+            else if (status.state === "Pending") {
+                message += " — waiting for approver response.";
+            }
+            else if (status.state === "Expired") {
+                message += " — the request has expired.";
+            }
+            else if (status.state === "Withdrawn") {
+                message += " — the request was withdrawn.";
+            }
+            return { state: status.state, message };
+        }
+        catch (err) {
+            if (err instanceof AirlockGatewayError && err.statusCode === 404) {
+                return {
+                    state: "not_found",
+                    message: `Exchange ${input.requestId} not found. It may have expired or been withdrawn.`,
+                };
+            }
+            return {
+                state: "error",
+                message: `Failed to check status: ${err instanceof Error ? err.message : String(err)}`,
+            };
+        }
+    });
+}
+//# sourceMappingURL=checkStatus.js.map

package/dist/tools/checkStatus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkStatus.js","sourceRoot":"","sources":["../../src/tools/checkStatus.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAkB9D,iDAAiD;AACjD,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,IAAI,EAAE,sBAAsB;IAC5B,WAAW,EACT,uEAAuE;QACvE,2DAA2D;IAC7D,WAAW,EAAE;QACX,IAAI,EAAE,QAAiB;QACvB,QAAQ,EAAE,CAAC,WAAW,CAAU;QAChC,UAAU,EAAE;YACV,SAAS,EAAE;gBACT,IAAI,EAAE,QAAiB;gBACvB,WAAW,EAAE,0DAA0D;aACxE;SACF;KACF;CACF,CAAC;AAEF;;GAEG;AACH,MAAM,UAAU,uBAAuB,CACrC,GAA4F,EAC5F,MAAqB,EACrB,OAAsB;IAEtB,GAAG,CAAC,YAAY,CAAC,kBAAkB,EAAE,KAAK,EAAE,QAAiB,EAAE,EAAE;QAC/D,MAAM,KAAK,GAAG,QAA4B,CAAC;QAE3C,IAAI,CAAC,KAAK,CAAC,SAAS,EAAE,IAAI,EAAE,EAAE,CAAC;YAC7B,OAAO;gBACL,KAAK,EAAE,OAAO;gBACd,OAAO,EAAE,uBAAuB;aACL,CAAC;QAChC,CAAC;QAED,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,iBAAiB,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;YAE/D,IAAI,OAAO,GAAG,YAAY,KAAK,CAAC,SAAS,KAAK,MAAM,CAAC,KAAK,EAAE,CAAC;YAE7D,IAAI,MAAM,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;gBAC/B,OAAO,IAAI,8BAA8B,CAAC;YAC5C,CAAC;iBAAM,IAAI,MAAM,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;gBACtC,OAAO,IAAI,mCAAmC,CAAC;YACjD,CAAC;iBAAM,IAAI,MAAM,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;gBACtC,OAAO,IAAI,6BAA6B,CAAC;YAC3C,CAAC;iBAAM,IAAI,MAAM,CAAC,KAAK,KAAK,WAAW,EAAE,CAAC;gBACxC,OAAO,IAAI,+BAA+B,CAAC;YAC7C,CAAC;YAED,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,OAAO,EAA8B,CAAC;QACtE,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,GAAG,YAAY,mBAAmB,IAAI,GAAG,CAAC,UAAU,KAAK,GAAG,EAAE,CAAC;gBACjE,OAAO;oBACL,KAAK,EAAE,WAAW;oBAClB,OAAO,EAAE,YAAY,KAAK,CAAC,SAAS,oDAAoD;iBAC7D,CAAC;YAChC,CAAC;YAED,OAAO;gBACL,KAAK,EAAE,OAAO;gBACd,OAAO,EAAE,2BAA2B,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE;aAC3D,CAAC;QAChC,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/tools/requestApproval.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Tool: requestApproval — AI-callable tool for explicit approval requests.
+ *
+ * The agent calls this tool when it wants to get approval for an action
+ * before executing it. Unlike the beforeTool hook (which intercepts
+ * automatically), this tool gives the agent explicit control.
+ *
+ * Respects DND (Do Not Disturb) policies — if DND is active, auto-approves.
+ */
+import type { AirlockClient } from "../client.js";
+import type { AirlockConfig } from "../config.js";
+/** Input schema for the requestApproval tool. */
+export interface RequestApprovalInput {
+    /** The action requiring approval (e.g. "deploy to production"). */
+    action: string;
+    /** Why this action needs approval. */
+    reason: string;
+    /** Additional context about the action. */
+    context?: string;
+}
+/** Output schema for the requestApproval tool. */
+export interface RequestApprovalOutput {
+    /** The decision: "approved", "rejected", or "timeout". */
+    decision: "approved" | "rejected" | "timeout";
+    /** The exchange request ID (for follow-up status checks). */
+    requestId: string;
+    /** Optional message from the approver or system. */
+    message?: string;
+}
+/** Tool definition for OpenClaw registration. */
+export declare const requestApprovalToolDef: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        required: readonly ["action", "reason"];
+        properties: {
+            action: {
+                type: "string";
+                description: string;
+            };
+            reason: {
+                type: "string";
+                description: string;
+            };
+            context: {
+                type: "string";
+                description: string;
+            };
+        };
+    };
+};
+/**
+ * Register the requestApproval tool with the OpenClaw plugin API.
+ *
+ * @param api OpenClaw plugin API (api.registerTool)
+ * @param client AirlockClient instance
+ * @param config Validated AirlockConfig
+ */
+export declare function registerRequestApprovalTool(api: {
+    registerTool: (def: unknown, handler: (input: unknown) => Promise<unknown>) => void;
+}, client: AirlockClient, config: AirlockConfig): void;
+//# sourceMappingURL=requestApproval.d.ts.map

package/dist/tools/requestApproval.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"requestApproval.d.ts","sourceRoot":"","sources":["../../src/tools/requestApproval.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAY,MAAM,cAAc,CAAC;AAC5D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,iDAAiD;AACjD,MAAM,WAAW,oBAAoB;IACnC,mEAAmE;IACnE,MAAM,EAAE,MAAM,CAAC;IACf,sCAAsC;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,2CAA2C;IAC3C,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,kDAAkD;AAClD,MAAM,WAAW,qBAAqB;IACpC,0DAA0D;IAC1D,QAAQ,EAAE,UAAU,GAAG,UAAU,GAAG,SAAS,CAAC;IAC9C,6DAA6D;IAC7D,SAAS,EAAE,MAAM,CAAC;IAClB,oDAAoD;IACpD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,iDAAiD;AACjD,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;CAyBlC,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CACzC,GAAG,EAAE;IAAE,YAAY,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,KAAK,IAAI,CAAA;CAAE,EAC5F,MAAM,EAAE,aAAa,EACrB,MAAM,EAAE,aAAa,GACpB,IAAI,CA2CN"}

package/dist/tools/requestApproval.js

@@ -0,0 +1,85 @@
+/**
+ * Tool: requestApproval — AI-callable tool for explicit approval requests.
+ *
+ * The agent calls this tool when it wants to get approval for an action
+ * before executing it. Unlike the beforeTool hook (which intercepts
+ * automatically), this tool gives the agent explicit control.
+ *
+ * Respects DND (Do Not Disturb) policies — if DND is active, auto-approves.
+ */
+/** Tool definition for OpenClaw registration. */
+export const requestApprovalToolDef = {
+    name: "airlock_request_approval",
+    description: "Request human approval for an action via Airlock. " +
+        "Use this before executing high-risk operations like deployments, " +
+        "data mutations, or system configuration changes. " +
+        "The request will be sent to the mobile approver app.",
+    inputSchema: {
+        type: "object",
+        required: ["action", "reason"],
+        properties: {
+            action: {
+                type: "string",
+                description: "The action requiring approval (e.g. 'deploy to production', 'delete database')",
+            },
+            reason: {
+                type: "string",
+                description: "Why this action needs approval",
+            },
+            context: {
+                type: "string",
+                description: "Additional context about the action (optional)",
+            },
+        },
+    },
+};
+/**
+ * Register the requestApproval tool with the OpenClaw plugin API.
+ *
+ * @param api OpenClaw plugin API (api.registerTool)
+ * @param client AirlockClient instance
+ * @param config Validated AirlockConfig
+ */
+export function registerRequestApprovalTool(api, client, config) {
+    api.registerTool(requestApprovalToolDef, async (rawInput) => {
+        const input = rawInput;
+        // Check DND (Do Not Disturb) policies before sending approval request
+        const dndActive = await client.isDndActive();
+        if (dndActive) {
+            return {
+                decision: "approved",
+                requestId: "",
+                message: "Auto-approved — Do Not Disturb mode is active.",
+            };
+        }
+        const result = await client.requestApproval({
+            actionType: input.action,
+            commandText: input.reason,
+            description: `Approval requested: ${input.action}`,
+            context: input.context,
+        });
+        const output = {
+            decision: result.decision,
+            requestId: result.requestId,
+        };
+        // Build a meaningful message
+        if (result.decision === "approved") {
+            output.message = "Action approved by the human approver. Proceed.";
+        }
+        else if (result.decision === "rejected") {
+            output.message = result.reason ?? "Action rejected by the approver.";
+        }
+        else {
+            // timeout
+            if (config.failMode === "open") {
+                output.message = "Approval timed out. Proceeding (fail-open mode).";
+                output.decision = "approved"; // Override to approved in fail-open
+            }
+            else {
+                output.message = "Approval timed out. Action blocked (fail-closed mode).";
+            }
+        }
+        return output;
+    });
+}
+//# sourceMappingURL=requestApproval.js.map

package/dist/tools/requestApproval.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"requestApproval.js","sourceRoot":"","sources":["../../src/tools/requestApproval.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAyBH,iDAAiD;AACjD,MAAM,CAAC,MAAM,sBAAsB,GAAG;IACpC,IAAI,EAAE,0BAA0B;IAChC,WAAW,EACT,oDAAoD;QACpD,mEAAmE;QACnE,mDAAmD;QACnD,sDAAsD;IACxD,WAAW,EAAE;QACX,IAAI,EAAE,QAAiB;QACvB,QAAQ,EAAE,CAAC,QAAQ,EAAE,QAAQ,CAAU;QACvC,UAAU,EAAE;YACV,MAAM,EAAE;gBACN,IAAI,EAAE,QAAiB;gBACvB,WAAW,EAAE,gFAAgF;aAC9F;YACD,MAAM,EAAE;gBACN,IAAI,EAAE,QAAiB;gBACvB,WAAW,EAAE,gCAAgC;aAC9C;YACD,OAAO,EAAE;gBACP,IAAI,EAAE,QAAiB;gBACvB,WAAW,EAAE,gDAAgD;aAC9D;SACF;KACF;CACF,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,UAAU,2BAA2B,CACzC,GAA4F,EAC5F,MAAqB,EACrB,MAAqB;IAErB,GAAG,CAAC,YAAY,CAAC,sBAAsB,EAAE,KAAK,EAAE,QAAiB,EAAE,EAAE;QACnE,MAAM,KAAK,GAAG,QAAgC,CAAC;QAE/C,sEAAsE;QACtE,MAAM,SAAS,GAAG,MAAM,MAAM,CAAC,WAAW,EAAE,CAAC;QAC7C,IAAI,SAAS,EAAE,CAAC;YACd,OAAO;gBACL,QAAQ,EAAE,UAAU;gBACpB,SAAS,EAAE,EAAE;gBACb,OAAO,EAAE,gDAAgD;aAC1B,CAAC;QACpC,CAAC;QAED,MAAM,MAAM,GAAa,MAAM,MAAM,CAAC,eAAe,CAAC;YACpD,UAAU,EAAE,KAAK,CAAC,MAAM;YACxB,WAAW,EAAE,KAAK,CAAC,MAAM;YACzB,WAAW,EAAE,uBAAuB,KAAK,CAAC,MAAM,EAAE;YAClD,OAAO,EAAE,KAAK,CAAC,OAAO;SACvB,CAAC,CAAC;QAEH,MAAM,MAAM,GAA0B;YACpC,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,SAAS,EAAE,MAAM,CAAC,SAAS;SAC5B,CAAC;QAEF,6BAA6B;QAC7B,IAAI,MAAM,CAAC,QAAQ,KAAK,UAAU,EAAE,CAAC;YACnC,MAAM,CAAC,OAAO,GAAG,iDAAiD,CAAC;QACrE,CAAC;aAAM,IAAI,MAAM,CAAC,QAAQ,KAAK,UAAU,EAAE,CAAC;YAC1C,MAAM,CAAC,OAAO,GAAG,MAAM,CAAC,MAAM,IAAI,kCAAkC,CAAC;QACvE,CAAC;aAAM,CAAC;YACN,UAAU;YACV,IAAI,MAAM,CAAC,QAAQ,KAAK,MAAM,EAAE,CAAC;gBAC/B,MAAM,CAAC,OAAO,GAAG,kDAAkD,CAAC;gBACpE,MAAM,CAAC,QAAQ,GAAG,UAAU,CAAC,CAAC,oCAAoC;YACpE,CAAC;iBAAM,CAAC;gBACN,MAAM,CAAC,OAAO,GAAG,wDAAwD,CAAC;YAC5E,CAAC;QACH,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC,CAAC,CAAC;AACL,CAAC"}

package/openclaw.plugin.json

@@ -0,0 +1,69 @@
+{
+  "id": "openclaw-airlock",
+  "name": "Airlock Security Gateway",
+  "version": "1.0.2",
+  "description": "Enforces human-in-the-loop approval for risky AI actions via Airlock Gateway",
+  "configSchema": {
+    "type": "object",
+    "required": ["gatewayUrl", "enforcerId"],
+    "properties": {
+      "gatewayUrl": {
+        "type": "string",
+        "description": "Airlock Gateway base URL (e.g. https://gw.airlocks.io)"
+      },
+      "enforcerId": {
+        "type": "string",
+        "description": "Unique identifier for this enforcer instance"
+      },
+      "pat": {
+        "type": "string",
+        "description": "Personal Access Token for user authentication"
+      },
+      "clientId": {
+        "type": "string",
+        "description": "Enforcer App Client ID"
+      },
+      "clientSecret": {
+        "type": "string",
+        "description": "Enforcer App Client Secret"
+      },
+      "pairingCode": {
+        "type": "string",
+        "description": "Pre-generated device pairing code"
+      },
+      "workspaceName": {
+        "type": "string",
+        "description": "Human-readable workspace name",
+        "default": "OpenClaw Workspace"
+      },
+      "timeoutMs": {
+        "type": "number",
+        "description": "Approval timeout in milliseconds",
+        "default": 300000
+      },
+      "pollIntervalMs": {
+        "type": "number",
+        "description": "Decision poll interval in milliseconds (minimum 1000)",
+        "default": 3000
+      },
+      "failMode": {
+        "type": "string",
+        "enum": ["open", "closed"],
+        "description": "Behavior on timeout or error: open = allow, closed = block",
+        "default": "closed"
+      },
+      "protectedTools": {
+        "type": "array",
+        "items": { "type": "string" },
+        "description": "List of tool names requiring approval (empty = none protected)",
+        "default": []
+      },
+      "executionMode": {
+        "type": "string",
+        "enum": ["poll", "webhook"],
+        "description": "How to wait for decisions: poll (default) or webhook (future)",
+        "default": "poll"
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "openclaw-airlock",
+  "version": "0.4.7",
+  "description": "Airlock security gateway plugin for OpenClaw — enforces human-in-the-loop approval for AI tool use",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "license": "MIT",
+  "author": "Airlock",
+  "homepage": "https://airlockapp.io",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/airlockapp/gateway-clients.git",
+    "directory": "src/openclaw-airlock"
+  },
+  "bugs": {
+    "url": "https://github.com/airlockapp/gateway-clients/issues"
+  },
+  "keywords": [
+    "airlock",
+    "openclaw",
+    "security",
+    "human-in-the-loop",
+    "approval",
+    "enforcer",
+    "gateway",
+    "harp"
+  ],
+  "files": [
+    "dist",
+    "openclaw.plugin.json"
+  ],
+  "openclaw": {
+    "extensions": [
+      "./dist/index.js"
+    ],
+    "compat": {
+      "pluginApi": ">=2026.3.0",
+      "minGatewayVersion": "2026.3.0"
+    },
+    "build": {
+      "openclawVersion": "2026.3.12"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@airlockapp/gateway-sdk": "^0.4.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.3.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}