openclaw-airlock 0.4.7

package/README.md

@@ -0,0 +1,406 @@
+# Airlock Plugin for OpenClaw
+
+[![npm](https://img.shields.io/npm/v/@airlockapp/openclaw-airlock)](https://www.npmjs.com/package/@airlockapp/openclaw-airlock)
+
+Enforces human-in-the-loop approval for risky AI tool actions via the [Airlock Gateway](https://airlockapp.io).
+
+**Airlock Approver** (mobile app): [App Store](https://apps.apple.com/us/app/airlock-approver/id6760250865) · [Google Play](https://play.google.com/store/apps/details?id=com.airlockapp.io)
+
+## Features
+
+- **Tool-based approval** — AI calls `airlock_request_approval` for explicit approval
+- **Hook-based enforcement** — Automatically intercepts protected tool executions
+- **Polling-based decisions** — Long-polls the gateway for approver decisions
+- **Pre-generated pairing** — X25519 ECDH key exchange with mobile approver app
+- **Decision signature verification** — Ed25519 signatures prevent forgery
+- **DND (Do Not Disturb)** — Auto-approves when DND policies are active
+- **Presence heartbeat** — Mobile app shows enforcer online/offline status
+- **State persistence** — Pairing state survives restarts (`.airlock/pairing-state.json`)
+- **Fail modes** — Configurable fail-open or fail-closed on timeout/errors
+
+---
+
+## Installation
+
+### Prerequisites
+
+| Requirement | Details |
+|-------------|---------|
+| **OpenClaw** | An OpenClaw-compatible AI agent runtime |
+| **Node.js** | Version 18 or later (`node --version`) |
+| **Airlock Gateway** | Access to an Airlock Integrations Gateway (default: `igw.airlocks.io`) |
+| **Airlock Mobile App** | For approving/denying actions and generating pairing codes |
+| **Airlock Developer Account** | Required to create an Enforcer App and get API credentials (see below) |
+| **Personal Access Token (PAT)** | Created from the Platform or Mobile App (Settings → Access Tokens) |
+
+### Step 1 — Join the Airlock Developer Programme
+
+Before you can create an enforcer app, you must register as a developer.
+
+1. **Sign in** to the [Airlock Platform](https://platform.airlocks.io) with your Airlock account.
+2. Navigate to **Developer Programme** in the sidebar.
+3. Fill in the application form.
+4. **Submit** your application. An Airlock administrator will review it.
+5. Once **Approved**, you can create enforcer apps.
+
+> For the full walkthrough with field descriptions and application states, see the [Airlock Developer Guide](https://airlockapp.io/docs/developer-guide/).
+
+### Step 2 — Create an Enforcer App
+
+Once approved, create an app from **Developer Programme → My Apps** in the Platform web UI.
+
+| Field | Value |
+|-------|-------|
+| **Name** | Your app name (e.g. "My OpenClaw Enforcer"). Must be unique. Max 128 characters. |
+| **Kind** | Select **Agent** (confidential client — authenticates via Client ID + Client Secret) |
+| **Is Open Source** | Whether your enforcer source code is public |
+| **Description** | What your app does (max 2000 chars) |
+
+On creation, you receive:
+
+| Credential | Description |
+|------------|-------------|
+| **App ID** | Human-readable identifier (format: `ABC-1234567`) |
+| **Client ID** | 20-character alphanumeric string (used in plugin config) |
+| **Client Secret** | 40-character secret (**shown only once** — copy and save it!) |
+
+> ⚠️ **Save the Client Secret immediately.** You cannot retrieve it later. You can rotate it from the Platform UI, but the old secret is invalidated.
+
+### Step 3 — Create a Personal Access Token (PAT)
+
+The plugin authenticates as a user via a **Personal Access Token**.
+
+1. In the **Airlock Platform App** (Settings → Access Tokens) or the **Mobile Approver** app, create a new token.
+2. Set an appropriate expiry (max 1 year).
+3. Copy the token (prefixed with `airpat_`).
+
+The token identifies which user the enforcer acts on behalf of.
+
+### Step 4 — Generate a Pre-Generated Pairing Code
+
+The OpenClaw plugin uses **pre-generated pairing codes** (approver-initiated) instead of interactive pairing. This means the approver creates the code first, and you paste it into the plugin config.
+
+**From the Mobile Approver app:**
+
+1. Open the **Airlock** mobile app on your phone.
+2. Tap the **"+"** button or go to **Workspaces → Add Workspace**.
+3. Select **"Generate Code"** (pre-generated pairing).
+4. The app shows a **6-character pairing code** (e.g. `A3K9X2`).
+5. Copy or note this code — you'll paste it into your plugin config.
+
+> ⏱️ **Time limit**: Pre-generated codes expire after **30 minutes**. Complete plugin setup within this window.
+
+The code is in **Pending** state until an enforcer claims it. You can see its status in the mobile app.
+
+### Step 5 — Install the Plugin
+
+**From npm** (recommended):
+
+```bash
+npm install @airlockapp/openclaw-airlock
+```
+
+**From your OpenClaw workspace:**
+
+```bash
+openclaw plugins install @airlockapp/openclaw-airlock
+```
+
+**From source** (for development):
+
+```bash
+cd gateway_sdk/src/openclaw-airlock
+npm install
+npm run build
+```
+
+### Step 6 — Configure the Plugin
+
+Add to your OpenClaw plugin config:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "airlock": {
+        "enabled": true,
+        "config": {
+          "gatewayUrl": "https://igw.airlocks.io",
+          "enforcerId": "my-enforcer-001",
+          "pat": "airpat_your_token_here",
+          "clientId": "ABCDEFGHJKLMNPRSTUVWXYZabc",
+          "clientSecret": "abcdEFGH1234567890abcdEFGH1234567890abcd",
+          "pairingCode": "A3K9X2",
+          "workspaceName": "My AI Workspace",
+          "failMode": "closed",
+          "protectedTools": ["exec", "shell.*", "deploy.run", "*"],
+          "timeoutMs": 300000,
+          "executionMode": "poll"
+        }
+      }
+    }
+  }
+}
+```
+
+### Config Reference
+
+| Field | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `gatewayUrl` | ✓ | — | Airlock Integrations Gateway URL (use `https://igw.airlocks.io` for production) |
+| `enforcerId` | ✓ | — | Unique enforcer instance identifier (your choice, e.g. `oc-prod-001`) |
+| `pat` | ✓* | — | Personal Access Token (`airpat_...`) |
+| `clientId` | ✓* | — | Enforcer App Client ID (from Step 2) |
+| `clientSecret` | ✓* | — | Enforcer App Client Secret (from Step 2) |
+| `pairingCode` | — | — | Pre-generated pairing code from mobile app (from Step 4) |
+| `workspaceName` | — | "OpenClaw Workspace" | Human-readable workspace name shown in mobile app |
+| `timeoutMs` | — | 300000 | Approval timeout in ms (default: 5 min) |
+| `pollIntervalMs` | — | 3000 | Decision poll interval in ms (min 1000) |
+| `failMode` | — | "closed" | `"open"` = allow on timeout, `"closed"` = block |
+| `protectedTools` | — | [] | Tool names requiring approval (empty = none) |
+| `executionMode` | — | "poll" | `"poll"` (only mode available) |
+
+> *`pat` is required for user identity. At least `clientId` **or** `pat` is required for authentication.
+
+### Step 7 — Pair and Verify
+
+Once configured, run the setup and pairing commands:
+
+```bash
+# Validate config and test gateway connectivity
+openclaw airlock setup
+
+# Claim the pre-generated pairing code (X25519 ECDH key exchange)
+openclaw airlock pair
+
+# Check everything is connected
+/airlock-status
+```
+
+The `airlock pair` command:
+1. Generates an X25519 keypair for end-to-end encryption
+2. Claims the pre-generated code with the gateway
+3. Polls until the mobile app completes the pairing
+4. Derives the shared AES-256-GCM encryption key via ECDH + HKDF-SHA256
+5. Stores the approver's Ed25519 public key for decision verification
+6. Persists all state to `.airlock/pairing-state.json`
+
+> 🔒 The `.airlock/` directory is automatically gitignored. It contains secrets (encryption key, routing token) that must not be committed.
+
+### Step 8 — You're Ready!
+
+After pairing, the plugin is fully operational:
+
+- **Protected tools** are automatically intercepted and require mobile approval
+- **Presence heartbeat** keeps the mobile app showing your workspace as online
+- **State persists** across restarts — no need to re-pair
+
+---
+
+## Usage
+
+### Automatic Enforcement (Hook)
+
+Configure `protectedTools` to automatically intercept tool executions:
+
+```json
+{
+  "protectedTools": ["shell.exec", "deploy.run", "database.query"]
+}
+```
+
+Any tool matching these names will require mobile approval before executing. Supports glob patterns (e.g. `shell.*` matches `shell.exec`, `shell.run`).
+
+When a DND (Do Not Disturb) policy is active, protected tools are auto-approved silently.
+
+### Explicit Approval (Tool)
+
+The AI agent can explicitly request approval using the `airlock_request_approval` tool:
+
+```
+Action: deploy to production
+Reason: User requested deployment of v2.1.0
+```
+
+This tool also respects DND policies.
+
+### Status Check (Tool)
+
+Check the status of a previous approval request using `airlock_check_status`:
+
+```
+Request ID: req-abc123
+```
+
+### Slash Command
+
+Use `/airlock-status` in chat to see the current status including:
+- Gateway connectivity
+- Pairing status and state file info
+- Encryption key availability
+- Protected tools list
+
+---
+
+## Fail Modes
+
+| Scenario | `failMode: "closed"` | `failMode: "open"` |
+|----------|----------------------|---------------------|
+| Approval timeout | ✗ Block | ✓ Allow |
+| Gateway unreachable | ✗ Block | ✓ Allow |
+| Network error | ✗ Block | ✓ Allow |
+| Pairing revoked | ✗ Block (always) | ✗ Block (always) |
+| No approver (stale) | ✗ Block (always) | ✗ Block (always) |
+| Quota exceeded | ✗ Block (always) | ✗ Block (always) |
+
+---
+
+## Security
+
+### End-to-End Encryption
+
+All approval requests are encrypted using AES-256-GCM. The encryption key is derived via:
+1. X25519 ECDH key exchange during pairing
+2. HKDF-SHA256 key derivation with info `"HARP-E2E-AES256GCM"`
+
+The gateway never sees the plaintext — it only routes encrypted artifacts.
+
+### Decision Signature Verification
+
+Approver decisions are signed with Ed25519. The plugin verifies signatures using the approver's public key stored during pairing. Canonical format: `${artifactHash}|${decision}|${nonce}`. Unsigned decisions are accepted; decisions with invalid signatures are rejected.
+
+### State Storage
+
+| Data | Location |
+|------|----------|
+| Routing token | `.airlock/pairing-state.json` |
+| Encryption key (AES-256-GCM) | `.airlock/pairing-state.json` |
+| Approver public keys | `.airlock/pairing-state.json` |
+| Pairing timestamp | `.airlock/pairing-state.json` |
+
+> ⚠️ **Security**: The `.airlock/` directory is gitignored by default. If you move or copy the project, ensure the state file is protected and not committed to version control.
+
+---
+
+## Troubleshooting
+
+### "Not paired — run 'airlock pair' first"
+- Make sure `pairingCode` is set in config.
+- Generate a new code if the previous one expired (30-min TTL).
+- Run `openclaw airlock pair`.
+
+### "No approver available — pairing may be stale"
+- The pairing was revoked from the mobile app.
+- Generate a new pre-generated code and run pair again.
+
+### "Access denied: pairing_revoked"
+- The mobile app user revoked the pairing.
+- The plugin automatically clears stale pairing state.
+- Generate a new code and run `openclaw airlock pair`.
+
+### "Approval timed out"
+- The approver didn't respond within the timeout period.
+- Increase `timeoutMs` if needed, or check if the approver's mobile app is reachable.
+
+### Plugin not intercepting tools
+- Check that `protectedTools` includes the tool names you want to gate.
+- An empty `protectedTools` array means no automatic enforcement (opt-in model).
+- OpenClaw's built-in shell/bash execution tool is named **`exec`** internally — not `bash` or `shell.exec`. Add `"exec"` to `protectedTools`, or use `"*"` to intercept all tools regardless of name.
+- Use the `airlock_request_approval` tool for explicit control.
+
+### Gateway unreachable
+- Verify the `gatewayUrl` is correct (`https://igw.airlocks.io` for production).
+- Run `openclaw airlock setup` to test connectivity.
+- Check network/firewall settings.
+
+---
+
+## Development
+
+```bash
+npm install
+npm run build        # Compile TypeScript
+npm run dev          # Watch mode
+npm run typecheck    # Type-check without emitting
+```
+
+### Project Structure
+
+```
+gateway_sdk/src/openclaw-airlock/
+  openclaw.plugin.json          # OpenClaw manifest + config schema
+  package.json                  # @airlockapp/openclaw-airlock npm package
+  tsconfig.json                 # TypeScript ESM config
+  .gitignore                    # Excludes .airlock/, dist/, node_modules/
+
+  src/
+    index.ts                    # Plugin entry — registers all capabilities
+    config.ts                   # Config parsing, validation, defaults
+    client.ts                   # Gateway SDK wrapper: approval, pairing, heartbeat, DND
+    crypto.ts                   # X25519 ECDH key exchange + Ed25519 signature verification
+    state.ts                    # Pairing state persistence (.airlock/pairing-state.json)
+
+    tools/
+      requestApproval.ts        # AI-callable tool: explicit approval request
+      checkStatus.ts            # AI-callable tool: check exchange status
+
+    hooks/
+      beforeTool.ts             # Automatic tool interception hook (+ DND check)
+
+    commands/
+      airlockStatus.ts          # /airlock-status diagnostic command
+
+    cli/
+      setup.ts                  # `airlock setup` — validate config + connectivity
+      pair.ts                   # `airlock pair` — claim pre-generated code
+```
+
+---
+
+## Architecture
+
+```
+┌───────────────────┐    HTTPS     ┌──────────────────────────┐
+│  OpenClaw Agent    │ ──────────→ │  Integrations Gateway     │
+│  + Airlock Plugin  │ ←────────── │  (igw.airlocks.io)        │
+└───────────────────┘              └────────────┬─────────────┘
+                                                │
+                                     Internal routing
+                                                │
+                                   ┌────────────▼─────────────┐
+                                   │  Airlock Platform Backend │
+                                   └────────────┬─────────────┘
+                                                │
+                                     Push notification
+                                                │
+                                   ┌────────────▼─────────────┐
+                                   │  Mobile Approver App      │
+                                   │  (approve / deny)         │
+                                   └──────────────────────────┘
+```
+
+Key components:
+
+- **@airlockapp/gateway-sdk** — TypeScript SDK for the Airlock Integrations Gateway API
+- **X25519 ECDH** — Key exchange for end-to-end encryption (AES-256-GCM)
+- **Ed25519** — Decision signature verification
+- **PAT + Client Credentials** — Dual authentication (user identity + app identity)
+- **Pre-generated pairing codes** — Config-driven pairing (no interactive browser login)
+- **Long-polling** — Server-side 25s timeout for efficient decision waiting
+- **Presence heartbeat** — 45s interval for online/offline status in mobile app
+- **DND policy check** — Auto-approval when Do Not Disturb is active
+
+---
+
+## Further Reading
+
+- [Airlock Developer Guide](https://airlockapp.io/docs/developer-guide/) — Developer programme, enforcer lifecycle, API reference
+- [Gateway Client SDKs](https://airlockapp.io/docs/sdk/) — Published SDK packages and documentation
+- [Gateway SDK (TypeScript)](../typescript/README.md) — TypeScript SDK documentation
+- [HARP Specification](../../../harp-spec/) — Human-Approvable Request Protocol specification
+
+---
+
+## License
+
+MIT

package/dist/cli/register.d.ts

@@ -0,0 +1,22 @@
+/**
+ * CLI registration — registers all Airlock CLI subcommands under `openclaw airlock`.
+ *
+ * All subcommands are registered in a single `registerCli` call because
+ * OpenClaw deduplicates by top-level command name: if "airlock" is already
+ * claimed, subsequent registrars for the same command are skipped.
+ *
+ * Subcommands:
+ *   openclaw airlock setup   — Validate config and test gateway connectivity
+ *   openclaw airlock consent — Trigger and wait for user consent on the mobile app
+ *   openclaw airlock pair    — Claim a pre-generated pairing code
+ */
+import type { AirlockClient } from "../client.js";
+import type { AirlockConfig } from "../config.js";
+export declare function registerCliCommands(api: {
+    registerCli?(registrar: (ctx: {
+        program: unknown;
+    }) => void | Promise<void>, opts?: {
+        commands?: string[];
+    }): void;
+}, client: AirlockClient, config: AirlockConfig): void;
+//# sourceMappingURL=register.d.ts.map

package/dist/cli/register.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.d.ts","sourceRoot":"","sources":["../../src/cli/register.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,wBAAgB,mBAAmB,CACjC,GAAG,EAAE;IACH,WAAW,CAAC,CACV,SAAS,EAAE,CAAC,GAAG,EAAE;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,EAC9D,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,GAC7B,IAAI,CAAC;CACT,EACD,MAAM,EAAE,aAAa,EACrB,MAAM,EAAE,aAAa,GACpB,IAAI,CAyQN"}

package/dist/cli/register.js

@@ -0,0 +1,229 @@
+/**
+ * CLI registration — registers all Airlock CLI subcommands under `openclaw airlock`.
+ *
+ * All subcommands are registered in a single `registerCli` call because
+ * OpenClaw deduplicates by top-level command name: if "airlock" is already
+ * claimed, subsequent registrars for the same command are skipped.
+ *
+ * Subcommands:
+ *   openclaw airlock setup   — Validate config and test gateway connectivity
+ *   openclaw airlock consent — Trigger and wait for user consent on the mobile app
+ *   openclaw airlock pair    — Claim a pre-generated pairing code
+ */
+export function registerCliCommands(api, client, config) {
+    if (!api.registerCli)
+        return;
+    api.registerCli(({ program }) => {
+        const airlockCmd = program
+            .command("airlock")
+            .description("Airlock security gateway");
+        // ── airlock setup ───────────────────────────────────────
+        airlockCmd
+            .command("setup")
+            .description("Validate Airlock configuration and test gateway connectivity")
+            .action(async () => {
+            // Ensure pairing state is loaded from disk before checking config
+            await client.ensureInitialized();
+            console.log("Airlock Setup");
+            console.log("═".repeat(40));
+            // 1. Config summary
+            console.log(`\nGateway URL:    ${config.gatewayUrl}`);
+            console.log(`Enforcer ID:   ${config.enforcerId}`);
+            console.log(`Workspace:     ${config.workspaceName}`);
+            console.log(`Fail Mode:     ${config.failMode}`);
+            console.log(`Auth (PAT):    ${config.pat ? "✓" : "✗"}`);
+            console.log(`Auth (Client): ${config.clientId ? "✓" : "✗"}`);
+            // 2. Gateway connectivity
+            console.log("\nTesting gateway connectivity...");
+            const health = await client.checkHealth();
+            if (health.connected) {
+                console.log(`✓ Connected to ${health.gatewayUrl}`);
+                if (health.serverTime) {
+                    console.log(`  Server time: ${health.serverTime}`);
+                }
+            }
+            else {
+                console.error(`✗ Cannot reach gateway: ${health.error}`);
+                console.error("  Check the gatewayUrl in your plugin config.");
+                return;
+            }
+            // 3. Consent status
+            try {
+                const consent = await client.checkConsent();
+                if (consent.status === "approved") {
+                    console.log("\n✓ App consent: approved");
+                }
+                else if (consent.status === "required") {
+                    console.log("\n⚠ App consent: required — run 'openclaw airlock consent' to trigger approval");
+                    if (consent.message)
+                        console.log(`  ${consent.message}`);
+                }
+                else if (consent.status === "pending") {
+                    console.log("\n⏳ App consent: pending — check your Airlock mobile app");
+                }
+                else if (consent.status === "denied") {
+                    console.error("\n✗ App consent: denied by user");
+                    if (consent.message)
+                        console.error(`  ${consent.message}`);
+                }
+            }
+            catch {
+                console.log("\n⚠ App consent: could not check (non-fatal)");
+            }
+            // 4. Pairing status
+            if (config.routingToken && config.encryptionKey) {
+                console.log("\n✓ Paired — ready to enforce");
+            }
+            else if (config.pairingCode) {
+                console.log("\n⚠ Not paired — run 'openclaw airlock pair' to claim your pairing code");
+            }
+            else {
+                console.log("\n⚠ Not paired — configure a pairingCode and run 'openclaw airlock pair'");
+            }
+            // 5. Protected tools
+            if (config.protectedTools.length > 0) {
+                console.log(`\nProtected tools (${config.protectedTools.length}):`);
+                for (const tool of config.protectedTools) {
+                    console.log(`  • ${tool}`);
+                }
+            }
+            else {
+                console.log("\nNo tools protected via hook (opt-in model).");
+                console.log("Use the airlock_request_approval tool for explicit approval.");
+            }
+            console.log("\n✓ Setup complete");
+        });
+        // ── airlock consent ─────────────────────────────────────
+        airlockCmd
+            .command("consent")
+            .description("Trigger and wait for user consent on the Airlock mobile app")
+            .action(async () => {
+            await client.ensureInitialized();
+            console.log("Airlock Consent");
+            console.log("═".repeat(40));
+            console.log(`\nEnforcer ID:  ${config.enforcerId}`);
+            console.log(`Gateway:      ${config.gatewayUrl}`);
+            // Initial check — this triggers the consent push if first time
+            console.log("\nChecking consent status...");
+            let consent = await client.checkConsent();
+            if (consent.status === "approved") {
+                console.log("✓ Consent already granted — you're good to go.");
+                return;
+            }
+            if (consent.status === "denied") {
+                console.error("✗ Consent was denied by the user.");
+                console.error("  Ask the user to re-approve in the Airlock mobile app.");
+                if (consent.consentUrl) {
+                    console.error(`  Consent URL: ${consent.consentUrl}`);
+                }
+                return;
+            }
+            // Status is "required" or "pending" — show instructions and poll
+            console.log("\n┌─ Consent Required ──────────────────────────────┐");
+            if (consent.message) {
+                console.log(`│ ${consent.message}`);
+            }
+            console.log("│ A consent request has been sent to the user's");
+            console.log("│ Airlock mobile app. Please approve it there.");
+            if (consent.consentUrl) {
+                console.log(`│ Or open: ${consent.consentUrl}`);
+            }
+            console.log("└─────────────────────────────────────────────────┘");
+            console.log("\nWaiting for consent approval...");
+            // Poll every 5 seconds for up to 5 minutes
+            const deadline = Date.now() + 5 * 60 * 1000;
+            let pollCount = 0;
+            while (Date.now() < deadline) {
+                await new Promise((r) => setTimeout(r, 5000));
+                pollCount++;
+                try {
+                    consent = await client.checkConsent();
+                }
+                catch {
+                    console.log(`  Poll ${pollCount}: error (retrying...)`);
+                    continue;
+                }
+                if (consent.status === "approved") {
+                    console.log(`\n✓ Consent granted! (after ${pollCount * 5}s)`);
+                    console.log("  You can now proceed with 'openclaw airlock pair'.");
+                    return;
+                }
+                if (consent.status === "denied") {
+                    console.error(`\n✗ Consent was denied. (after ${pollCount * 5}s)`);
+                    return;
+                }
+                const elapsed = pollCount * 5;
+                console.log(`  Waiting... (${elapsed}s elapsed, status: ${consent.status})`);
+            }
+            console.error("\n✗ Timed out waiting for consent (5 minutes).");
+            console.error("  Try again or check the Airlock mobile app.");
+        });
+        // ── airlock pair ────────────────────────────────────────
+        airlockCmd
+            .command("pair")
+            .description("Claim a pre-generated pairing code and establish encrypted communication")
+            .action(async () => {
+            // Ensure pairing state is loaded from disk before checking config
+            await client.ensureInitialized();
+            console.log("Airlock Pairing");
+            console.log("═".repeat(40));
+            // Check if already paired
+            if (config.routingToken && config.encryptionKey) {
+                console.log("✓ Already paired.");
+                console.log("  To re-pair, clear the existing pairing first.");
+                return;
+            }
+            // Check for pairing code
+            if (!config.pairingCode) {
+                console.error("✗ No pairing code configured.");
+                console.error("  Set 'pairingCode' in your Airlock plugin config.");
+                console.error("  Generate a code in the Airlock admin dashboard or mobile app.");
+                return;
+            }
+            // Test gateway connectivity first
+            const health = await client.checkHealth();
+            if (!health.connected) {
+                console.error(`✗ Cannot reach gateway: ${health.error}`);
+                console.error("  Fix connectivity before pairing.");
+                return;
+            }
+            // Check consent before attempting to pair
+            try {
+                const consent = await client.checkConsent();
+                if (consent.status !== "approved") {
+                    console.error("⚠ App consent not yet granted.");
+                    console.error("  Run 'openclaw airlock consent' first to get user approval.");
+                    return;
+                }
+            }
+            catch {
+                // Consent check failed — continue with pairing anyway
+                console.log("⚠ Could not verify consent status (continuing...)");
+            }
+            console.log(`Gateway:      ${config.gatewayUrl}`);
+            console.log(`Enforcer ID:  ${config.enforcerId}`);
+            console.log(`Workspace:    ${config.workspaceName}`);
+            console.log(`Pairing Code: ${config.pairingCode}`);
+            console.log("\nClaiming pairing code (X25519 ECDH key exchange)...");
+            try {
+                const result = await client.claimPairing(config.pairingCode);
+                console.log("\n✓ Pairing successful!");
+                console.log(`  Routing Token: ${result.routingToken.slice(0, 12)}...`);
+                console.log("  Encryption:    ✓ Key derived (X25519 ECDH + HKDF-SHA256)");
+                console.log("  State File:    ✓ Persisted to ~/.openclaw/.airlock/pairing-state.json");
+                console.log("\n  Airlock is now ready to enforce approvals.");
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                console.error(`\n✗ Pairing failed: ${msg}`);
+                if (msg.includes("expired")) {
+                    console.error("  Generate a new pairing code and update your config.");
+                }
+                if (msg.includes("x25519PublicKey")) {
+                    console.error("  The pairing response may be missing key exchange data.");
+                }
+            }
+        });
+    }, { commands: ["airlock"] });
+}
+//# sourceMappingURL=register.js.map

package/dist/cli/register.js.map

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