Mfa Gate

Name: Mfa Gate
Rating: 3.5 (1 reviews)
Author: percent-20

By percent-20 ⭐ 1 stars 👁 80 views ▲ 0 votes

Mist — MFA for AI agents. An OpenClaw channel plugin.

GitHub

Install

openclaw plugins install -l

Configuration Example

{
	"enabled": true,
	"instanceId": "oc_abc123...",
	"vaultUid": "v12345...",
	"accessToken": "abc123...",
	"apiBaseUrl": "http://localhost:3000",
	"pollIntervalMs": 500,
	"pollTimeoutMs": 120000
}

README

# Mist Channel — AirVaults MFA for OpenClaw

Routes OpenClaw approval requests through the AirVaults mobile app. When OpenClaw's built-in approval engine flags a risky action, the approval request flows through the **mist** channel to your phone — you tap approve or deny, and the decision is injected back into OpenClaw.

## How It Works

```
User runs risky command in OpenClaw
  -> OpenClaw approval engine detects risk
  -> Sends approval request to mist channel (outbound.sendText)
  -> mist-channel.js parses approval ID
  -> Creates challenge: POST /api/v2/mfa_vaults/:uid/challenge (PENDING)
  -> Polls: GET /api/v2/mfa_vaults/:uid/challenge/:id
  -> Mobile app sees pending challenge, user taps approve/deny
  -> Mobile app: POST /api/v2/mfa_vaults/:uid/challenge/:id/respond
  -> Poll returns decision
  -> mist-channel.js injects /approve or /deny back into OpenClaw
  -> OpenClaw executes or blocks the action
```

## Installation

Install from a local path using `--link` (symlinks instead of copying):

```bash
openclaw plugins install -l ./apps/openclaw-mfa-gate
```

Restart the gateway to load:

```bash
openclaw gateway restart
```

Verify:

```bash
openclaw plugins list
# Should show: Mist Channel (AirVaults MFA) — loaded — v2.0.0
```

### Managing the plugin

```bash
openclaw plugins info openclaw-mfa-gate   # Show details
openclaw plugins disable openclaw-mfa-gate # Disable (keeps files)
openclaw plugins enable openclaw-mfa-gate  # Re-enable
```

### Removing the plugin

OpenClaw 2026.2 does not have a `plugins uninstall` command. To remove:

1. Disable the plugin:
    ```bash
    openclaw plugins disable openclaw-mfa-gate
    ```
2. Remove the entry from `~/.openclaw/openclaw.json` — delete `openclaw-mfa-gate` from `plugins.entries`, `plugins.installs`, and `plugins.load.paths`.
3. If it was installed without `--link`, delete the extension directory:
    ```bash
    rm -rf ~/.openclaw/extensions/openclaw-mfa-gate
    ```
4. Restart the gateway.

## Setup (QR Onboarding)

1. **Generate QR code:**

    ```bash
    openclaw mfa
    ```

    Or in chat: use the `mfa_setup` tool.

2. **Scan QR** with AirVaults mobile app — the app creates an MFA vault.

3. **Copy the binding key** the app shows (`mfa:bind:vault_uid:access_token`).

4. **Bind** — send the key via the `mfa_bind` tool or paste it in any OpenClaw channel.

5. **Restart** the gateway. The mist channel is now active.

## Configuration

Config is stored in `config/mfa-config.json` (auto-saved by `mfa_bind`):

```json
{
	"enabled": true,
	"instanceId": "oc_abc123...",
	"vaultUid": "v12345...",
	"accessToken": "abc123...",
	"apiBaseUrl": "http://localhost:3000",
	"pollIntervalMs": 500,
	"pollTimeoutMs": 120000
}
```

Or configure via `openclaw.json` under `plugins.entries.openclaw-mfa-gate`.

## Tools

| Tool         | Description                              |
| ------------ | ---------------------------------------- |
| `mfa_setup`  | Generate QR code for mobile app binding  |
| `mfa_bind`   | Bind vault with key from mobile app      |
| `mfa_status` | Check vault status and recent challenges |

## CLI

```bash
openclaw mfa                  # Setup wizard with QR code
openclaw mfa --api-url URL    # Custom API URL
openclaw mfa --name NAME      # Custom instance name
```

## API Endpoints

| Method | Endpoint                                        | Description                |
| ------ | ----------------------------------------------- | -------------------------- |
| POST   | `/api/v2/mfa_vaults`                            | Create MFA vault           |
| POST   | `/api/v2/mfa_vaults/:uid/bind`                  | Bind instance              |
| POST   | `/api/v2/mfa_vaults/:uid/challenge`             | Create challenge (pending) |
| GET    | `/api/v2/mfa_vaults/:uid/challenge/:id`         | Poll challenge status      |
| POST   | `/api/v2/mfa_vaults/:uid/challenge/:id/respond` | Approve/deny challenge     |
| GET    | `/api/v2/mfa_vaults/:uid/pending_challenges`    | List pending challenges    |
| GET    | `/api/v2/mfa_vaults/:uid/status`                | Vault status               |

## Architecture

This plugin is a **pure channel adapter**. It does not detect risky actions — that's OpenClaw's job. The plugin only:

1. Receives approval requests from OpenClaw's approval engine
2. Creates challenges in the AirVaults API
3. Polls until the mobile app user responds
4. Injects `/approve` or `/deny` back into OpenClaw

No WebSocket, no hooks, no risk classification. Just HTTP polling.

## License

MIT

channels