port42-openclaw 0.1.0

package/.github/workflows/publish.yml

@@ -0,0 +1,25 @@
+name: Publish Package
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  id-token: write
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          registry-url: 'https://registry.npmjs.org'
+
+      - run: npm ci
+      - run: npm run build
+      - run: npm publish

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gordon J. Mattey
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,74 @@
+# port42-openclaw
+
+Port42 channel adapter for OpenClaw. Bring your OpenClaw agents into [Port42](https://port42.ai) companion computing channels.
+
+## Install
+
+```bash
+openclaw plugins install port42-openclaw
+```
+
+## Usage
+
+Someone shares a Port42 channel invite link with you. Add it to OpenClaw:
+
+```bash
+openclaw channel add port42 \
+  --invite "https://your-host.ngrok-free.dev/invite?id=CHANNEL-UUID&name=my-channel&key=BASE64KEY" \
+  --agent my-researcher \
+  --name "Researcher"
+```
+
+Your agent appears in the Port42 channel. People can @mention it and it responds alongside other companions in the room.
+
+### Manual config
+
+Or edit `openclaw.json` directly:
+
+```json
+{
+  "channels": {
+    "port42-project": {
+      "type": "port42",
+      "invite": "https://your-host.ngrok-free.dev/invite?id=CHANNEL-UUID&name=my-channel&key=BASE64KEY",
+      "displayName": "Researcher",
+      "trigger": "mention"
+    }
+  }
+}
+```
+
+### Config options
+
+| Option | Required | Default | Description |
+|--------|----------|---------|-------------|
+| `invite` | yes* | — | Port42 HTTPS invite link |
+| `gateway` | yes* | — | WebSocket URL (derived from invite if provided) |
+| `channelId` | yes* | — | Channel UUID (parsed from invite if provided) |
+| `encryptionKey` | no | — | AES-256 key (parsed from invite if provided) |
+| `displayName` | yes | — | How the agent appears in Port42 |
+| `trigger` | no | `mention` | `mention` (respond to @name) or `all` (respond to everything) |
+
+*Provide either `invite` or both `gateway` + `channelId`.
+
+## How it works
+
+The adapter connects to a Port42 gateway as a regular peer over WebSocket. From Port42's perspective, your OpenClaw agent is just another companion in the channel.
+
+- Messages are end-to-end encrypted (AES-256-GCM) using the channel key from the invite link
+- The agent shows up in the presence list when connected
+- Typing indicators show when the agent is generating a response
+- Auto-reconnects if the connection drops
+
+## Building from source
+
+```bash
+git clone https://github.com/gordonmattey/port42-openclaw.git
+cd port42-openclaw
+npm install
+npm run build
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/dist/connection.d.ts

@@ -0,0 +1,33 @@
+/**
+ * WebSocket connection to a Port42 gateway with reconnection.
+ */
+export interface ConnectionConfig {
+    gateway: string;
+    channelId: string;
+    senderId: string;
+    displayName: string;
+    encryptionKey: string | null;
+    trigger: 'mention' | 'all';
+    onMessage: (senderName: string, content: string, messageId: string) => void;
+    onPresence?: (onlineIds: string[]) => void;
+    onConnected?: () => void;
+    onDisconnected?: () => void;
+}
+export declare class Port42Connection {
+    private ws;
+    private config;
+    private reconnectDelay;
+    private maxReconnectDelay;
+    private shouldReconnect;
+    private identified;
+    constructor(config: ConnectionConfig);
+    connect(): void;
+    disconnect(): void;
+    sendResponse(content: string): void;
+    sendTyping(isTyping: boolean): void;
+    private openSocket;
+    private handleEnvelope;
+    private handleIncomingMessage;
+    private send;
+    private scheduleReconnect;
+}

package/dist/connection.js

@@ -0,0 +1,159 @@
+"use strict";
+/**
+ * WebSocket connection to a Port42 gateway with reconnection.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Port42Connection = void 0;
+const ws_1 = __importDefault(require("ws"));
+const protocol_1 = require("./protocol");
+const crypto_1 = require("./crypto");
+class Port42Connection {
+    ws = null;
+    config;
+    reconnectDelay = 3000;
+    maxReconnectDelay = 30000;
+    shouldReconnect = true;
+    identified = false;
+    constructor(config) {
+        this.config = config;
+    }
+    connect() {
+        this.shouldReconnect = true;
+        this.openSocket();
+    }
+    disconnect() {
+        this.shouldReconnect = false;
+        if (this.ws && this.ws.readyState === ws_1.default.OPEN) {
+            this.send((0, protocol_1.createLeave)(this.config.channelId));
+            this.ws.close();
+        }
+        this.ws = null;
+        this.config.onDisconnected?.();
+    }
+    sendResponse(content) {
+        if (!this.ws || this.ws.readyState !== ws_1.default.OPEN)
+            return;
+        if (this.config.encryptionKey) {
+            const payload = {
+                content,
+                senderName: this.config.displayName,
+                senderOwner: null,
+                replyToId: null,
+            };
+            const blob = (0, crypto_1.encrypt)(payload, this.config.encryptionKey);
+            this.send((0, protocol_1.createMessage)(this.config.channelId, this.config.senderId, this.config.displayName, blob, true));
+        }
+        else {
+            this.send((0, protocol_1.createMessage)(this.config.channelId, this.config.senderId, this.config.displayName, content, false));
+        }
+    }
+    sendTyping(isTyping) {
+        if (!this.ws || this.ws.readyState !== ws_1.default.OPEN)
+            return;
+        this.send((0, protocol_1.createTyping)(this.config.channelId, this.config.senderId, isTyping));
+    }
+    openSocket() {
+        try {
+            this.ws = new ws_1.default(this.config.gateway);
+        }
+        catch (err) {
+            console.error('[port42] Failed to create WebSocket:', err);
+            this.scheduleReconnect();
+            return;
+        }
+        this.ws.on('open', () => {
+            this.reconnectDelay = 3000;
+            this.identified = false;
+            this.send((0, protocol_1.createIdentify)(this.config.senderId, this.config.displayName));
+        });
+        this.ws.on('message', (data) => {
+            try {
+                const envelope = JSON.parse(data.toString());
+                this.handleEnvelope(envelope);
+            }
+            catch (err) {
+                console.error('[port42] Failed to parse message:', err);
+            }
+        });
+        this.ws.on('close', () => {
+            this.identified = false;
+            this.config.onDisconnected?.();
+            this.scheduleReconnect();
+        });
+        this.ws.on('error', (err) => {
+            console.error('[port42] WebSocket error:', err.message);
+        });
+    }
+    handleEnvelope(envelope) {
+        switch (envelope.type) {
+            case 'welcome':
+                this.identified = true;
+                this.send((0, protocol_1.createJoin)(this.config.channelId));
+                this.config.onConnected?.();
+                break;
+            case 'message':
+                this.handleIncomingMessage(envelope);
+                break;
+            case 'presence':
+                if (envelope.online_ids) {
+                    this.config.onPresence?.(envelope.online_ids);
+                }
+                break;
+            case 'error':
+                console.error('[port42] Gateway error:', envelope.error);
+                break;
+            case 'ack':
+                // Message delivered
+                break;
+        }
+    }
+    handleIncomingMessage(envelope) {
+        if (!envelope.payload || !envelope.message_id)
+            return;
+        // Ignore own messages
+        if (envelope.sender_id === this.config.senderId)
+            return;
+        // ACK receipt
+        this.send((0, protocol_1.createAck)(envelope.message_id, this.config.channelId));
+        // Decrypt if needed
+        let content;
+        let senderName;
+        if (envelope.payload.encrypted && this.config.encryptionKey) {
+            const decrypted = (0, crypto_1.decrypt)(envelope.payload.content, this.config.encryptionKey);
+            if (!decrypted) {
+                console.error('[port42] Decryption failed for message:', envelope.message_id);
+                return;
+            }
+            content = decrypted.content;
+            senderName = decrypted.senderName || envelope.sender_name || 'Unknown';
+        }
+        else {
+            content = envelope.payload.content;
+            senderName = envelope.payload.senderName || envelope.sender_name || 'Unknown';
+        }
+        // Check trigger rules
+        if (this.config.trigger === 'mention') {
+            const mentionPattern = new RegExp(`@${this.config.displayName}\\b`, 'i');
+            if (!mentionPattern.test(content))
+                return;
+        }
+        this.config.onMessage(senderName, content, envelope.message_id);
+    }
+    send(envelope) {
+        if (this.ws && this.ws.readyState === ws_1.default.OPEN) {
+            this.ws.send(JSON.stringify(envelope));
+        }
+    }
+    scheduleReconnect() {
+        if (!this.shouldReconnect)
+            return;
+        console.log(`[port42] Reconnecting in ${this.reconnectDelay / 1000}s...`);
+        setTimeout(() => this.openSocket(), this.reconnectDelay);
+        this.reconnectDelay = Math.min(this.reconnectDelay * 2, this.maxReconnectDelay);
+    }
+}
+exports.Port42Connection = Port42Connection;
+//# sourceMappingURL=connection.js.map

package/dist/crypto.d.ts

@@ -0,0 +1,8 @@
+/**
+ * AES-256-GCM encryption/decryption matching Port42's ChannelCrypto.
+ *
+ * Wire format: base64(nonce[12] + ciphertext + tag[16])
+ */
+import type { Payload } from './protocol';
+export declare function encrypt(payload: Payload, keyBase64: string): string;
+export declare function decrypt(blob: string, keyBase64: string): Payload | null;

package/dist/crypto.js

@@ -0,0 +1,44 @@
+"use strict";
+/**
+ * AES-256-GCM encryption/decryption matching Port42's ChannelCrypto.
+ *
+ * Wire format: base64(nonce[12] + ciphertext + tag[16])
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encrypt = encrypt;
+exports.decrypt = decrypt;
+const node_crypto_1 = require("node:crypto");
+const ALGORITHM = 'aes-256-gcm';
+const NONCE_LENGTH = 12;
+const TAG_LENGTH = 16;
+function encrypt(payload, keyBase64) {
+    const key = Buffer.from(keyBase64, 'base64');
+    const nonce = (0, node_crypto_1.randomBytes)(NONCE_LENGTH);
+    const cleartext = JSON.stringify(payload);
+    const cipher = (0, node_crypto_1.createCipheriv)(ALGORITHM, key, nonce);
+    const encrypted = Buffer.concat([cipher.update(cleartext, 'utf8'), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    // nonce + ciphertext + tag
+    const blob = Buffer.concat([nonce, encrypted, tag]);
+    return blob.toString('base64');
+}
+function decrypt(blob, keyBase64) {
+    try {
+        const key = Buffer.from(keyBase64, 'base64');
+        const data = Buffer.from(blob, 'base64');
+        if (data.length < NONCE_LENGTH + TAG_LENGTH) {
+            return null;
+        }
+        const nonce = data.subarray(0, NONCE_LENGTH);
+        const tag = data.subarray(data.length - TAG_LENGTH);
+        const ciphertext = data.subarray(NONCE_LENGTH, data.length - TAG_LENGTH);
+        const decipher = (0, node_crypto_1.createDecipheriv)(ALGORITHM, key, nonce);
+        decipher.setAuthTag(tag);
+        const decrypted = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+        return JSON.parse(decrypted.toString('utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=crypto.js.map

package/dist/index.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Port42 channel adapter for OpenClaw.
+ *
+ * Bridges OpenClaw agents into Port42 companion computing channels.
+ * Users install with: openclaw plugins install port42-openclaw
+ * Then add a channel with a Port42 invite link.
+ */
+export interface Port42ChannelConfig {
+    invite?: string;
+    gateway?: string;
+    channelId?: string;
+    encryptionKey?: string;
+    displayName: string;
+    trigger?: 'mention' | 'all';
+}
+interface PluginAPI {
+    registerChannel(name: string, handler: ChannelHandler): void;
+    log: {
+        info(msg: string): void;
+        error(msg: string): void;
+        debug(msg: string): void;
+    };
+}
+interface ChannelHandler {
+    connect(config: Port42ChannelConfig): Promise<ChannelInstance>;
+}
+interface ChannelInstance {
+    send(content: string): Promise<void>;
+    disconnect(): Promise<void>;
+}
+/**
+ * OpenClaw plugin entry point.
+ */
+export declare function register(api: PluginAPI): void;
+export { parseInviteLink } from './invite';
+export { Port42Connection } from './connection';
+export type { ConnectionConfig } from './connection';
+export type { InviteConfig } from './invite';
+export { encrypt, decrypt } from './crypto';

package/dist/index.js

@@ -0,0 +1,120 @@
+"use strict";
+/**
+ * Port42 channel adapter for OpenClaw.
+ *
+ * Bridges OpenClaw agents into Port42 companion computing channels.
+ * Users install with: openclaw plugins install port42-openclaw
+ * Then add a channel with a Port42 invite link.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.decrypt = exports.encrypt = exports.Port42Connection = exports.parseInviteLink = void 0;
+exports.register = register;
+const invite_1 = require("./invite");
+const connection_1 = require("./connection");
+const node_crypto_1 = require("node:crypto");
+/**
+ * Generate a stable sender ID from the display name.
+ * This ensures the same agent gets the same ID across restarts
+ * so the gateway recognizes it as the same peer.
+ */
+function stableSenderId(displayName) {
+    const hash = (0, node_crypto_1.createHash)('sha256').update(`port42-openclaw:${displayName}`).digest('hex');
+    // Format as UUID-like string for compatibility
+    return [
+        hash.slice(0, 8),
+        hash.slice(8, 12),
+        hash.slice(12, 16),
+        hash.slice(16, 20),
+        hash.slice(20, 32),
+    ].join('-');
+}
+/**
+ * Resolve config from either an invite link or explicit fields.
+ */
+function resolveConfig(config) {
+    if (config.invite) {
+        const parsed = (0, invite_1.parseInviteLink)(config.invite);
+        return {
+            gateway: config.gateway || parsed.gateway,
+            channelId: config.channelId || parsed.channelId,
+            encryptionKey: config.encryptionKey || parsed.encryptionKey,
+        };
+    }
+    if (!config.gateway || !config.channelId) {
+        throw new Error('Port42 channel requires either an invite link or explicit gateway + channelId');
+    }
+    return {
+        gateway: config.gateway,
+        channelId: config.channelId,
+        encryptionKey: config.encryptionKey || null,
+    };
+}
+/**
+ * OpenClaw plugin entry point.
+ */
+function register(api) {
+    api.registerChannel('port42', {
+        async connect(config) {
+            const resolved = resolveConfig(config);
+            const senderId = stableSenderId(config.displayName);
+            const trigger = config.trigger || 'mention';
+            api.log.info(`Connecting to Port42 channel ${resolved.channelId} as "${config.displayName}"`);
+            return new Promise((resolve, reject) => {
+                let messageHandler = null;
+                const connection = new connection_1.Port42Connection({
+                    gateway: resolved.gateway,
+                    channelId: resolved.channelId,
+                    senderId,
+                    displayName: config.displayName,
+                    encryptionKey: resolved.encryptionKey,
+                    trigger,
+                    onMessage(senderName, content, messageId) {
+                        if (messageHandler) {
+                            messageHandler(senderName, content, messageId);
+                        }
+                    },
+                    onConnected() {
+                        api.log.info(`Connected to Port42 as "${config.displayName}"`);
+                        resolve({
+                            async send(content) {
+                                connection.sendTyping(true);
+                                // Small delay so typing indicator shows before response
+                                await new Promise((r) => setTimeout(r, 100));
+                                connection.sendResponse(content);
+                                connection.sendTyping(false);
+                            },
+                            async disconnect() {
+                                connection.disconnect();
+                                api.log.info(`Disconnected from Port42`);
+                            },
+                        });
+                    },
+                    onDisconnected() {
+                        api.log.debug('Port42 connection lost');
+                    },
+                    onPresence(onlineIds) {
+                        api.log.debug(`Port42 presence: ${onlineIds.length} online`);
+                    },
+                });
+                // Wire up the message handler for OpenClaw to receive inbound messages
+                messageHandler = (senderName, content, _messageId) => {
+                    api.log.debug(`[${senderName}]: ${content.slice(0, 100)}`);
+                };
+                connection.connect();
+                // Timeout if we can't connect within 15 seconds
+                setTimeout(() => {
+                    reject(new Error('Port42 connection timeout (15s)'));
+                }, 15000);
+            });
+        },
+    });
+}
+// Re-export modules for standalone use
+var invite_2 = require("./invite");
+Object.defineProperty(exports, "parseInviteLink", { enumerable: true, get: function () { return invite_2.parseInviteLink; } });
+var connection_2 = require("./connection");
+Object.defineProperty(exports, "Port42Connection", { enumerable: true, get: function () { return connection_2.Port42Connection; } });
+var crypto_1 = require("./crypto");
+Object.defineProperty(exports, "encrypt", { enumerable: true, get: function () { return crypto_1.encrypt; } });
+Object.defineProperty(exports, "decrypt", { enumerable: true, get: function () { return crypto_1.decrypt; } });
+//# sourceMappingURL=index.js.map

package/dist/invite.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Parse Port42 HTTPS invite links into connection config.
+ *
+ * Invite format:
+ * https://<host>/invite?id=<channel-uuid>&name=<channel-name>&key=<url-encoded-base64-aes-key>
+ */
+export interface InviteConfig {
+    gateway: string;
+    channelId: string;
+    channelName: string;
+    encryptionKey: string | null;
+}
+export declare function parseInviteLink(invite: string): InviteConfig;

package/dist/invite.js

@@ -0,0 +1,23 @@
+"use strict";
+/**
+ * Parse Port42 HTTPS invite links into connection config.
+ *
+ * Invite format:
+ * https://<host>/invite?id=<channel-uuid>&name=<channel-name>&key=<url-encoded-base64-aes-key>
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseInviteLink = parseInviteLink;
+function parseInviteLink(invite) {
+    const url = new URL(invite);
+    const channelId = url.searchParams.get('id');
+    if (!channelId) {
+        throw new Error('Invite link missing channel id (id= parameter)');
+    }
+    const channelName = url.searchParams.get('name') || 'unknown';
+    const encryptionKey = url.searchParams.get('key') || null;
+    // Derive WebSocket URL from the HTTPS host
+    const protocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
+    const gateway = `${protocol}//${url.host}/ws`;
+    return { gateway, channelId, channelName, encryptionKey };
+}
+//# sourceMappingURL=invite.js.map

package/dist/protocol.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Port42 gateway WebSocket protocol types.
+ */
+export type EnvelopeType = 'identify' | 'welcome' | 'join' | 'leave' | 'message' | 'ack' | 'presence' | 'typing' | 'error';
+export interface Envelope {
+    type: EnvelopeType;
+    channel_id?: string;
+    sender_id?: string;
+    sender_name?: string;
+    message_id?: string;
+    payload?: Payload;
+    timestamp?: number;
+    error?: string;
+    online_ids?: string[];
+    status?: 'online' | 'offline';
+    companion_ids?: string[];
+}
+export interface Payload {
+    content: string;
+    senderName?: string;
+    senderOwner?: string | null;
+    replyToId?: string | null;
+    encrypted?: boolean;
+}
+export declare function createIdentify(senderId: string, senderName: string): Envelope;
+export declare function createJoin(channelId: string, companionIds?: string[]): Envelope;
+export declare function createLeave(channelId: string): Envelope;
+export declare function createMessage(channelId: string, senderId: string, senderName: string, content: string, encrypted?: boolean): Envelope;
+export declare function createAck(messageId: string, channelId: string): Envelope;
+export declare function createTyping(channelId: string, senderId: string, isTyping: boolean): Envelope;

package/dist/protocol.js

@@ -0,0 +1,66 @@
+"use strict";
+/**
+ * Port42 gateway WebSocket protocol types.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createIdentify = createIdentify;
+exports.createJoin = createJoin;
+exports.createLeave = createLeave;
+exports.createMessage = createMessage;
+exports.createAck = createAck;
+exports.createTyping = createTyping;
+function createIdentify(senderId, senderName) {
+    return {
+        type: 'identify',
+        sender_id: senderId,
+        sender_name: senderName,
+    };
+}
+function createJoin(channelId, companionIds = []) {
+    return {
+        type: 'join',
+        channel_id: channelId,
+        companion_ids: companionIds,
+    };
+}
+function createLeave(channelId) {
+    return {
+        type: 'leave',
+        channel_id: channelId,
+    };
+}
+function createMessage(channelId, senderId, senderName, content, encrypted = false) {
+    return {
+        type: 'message',
+        channel_id: channelId,
+        sender_id: senderId,
+        sender_name: senderName,
+        message_id: crypto.randomUUID(),
+        payload: {
+            content,
+            senderName: encrypted ? '' : senderName,
+            senderOwner: null,
+            replyToId: null,
+            encrypted,
+        },
+        timestamp: Date.now(),
+    };
+}
+function createAck(messageId, channelId) {
+    return {
+        type: 'ack',
+        message_id: messageId,
+        channel_id: channelId,
+    };
+}
+function createTyping(channelId, senderId, isTyping) {
+    return {
+        type: 'typing',
+        channel_id: channelId,
+        sender_id: senderId,
+        payload: {
+            content: isTyping ? 'typing' : 'stopped',
+        },
+    };
+}
+//# sourceMappingURL=protocol.js.map

package/openclaw.plugin.json

@@ -0,0 +1,44 @@
+{
+  "name": "port42-openclaw",
+  "version": "0.1.0",
+  "description": "Port42 channel adapter — bring your OpenClaw agents into Port42 companion computing channels",
+  "type": "channel",
+  "entry": "dist/index.js",
+  "author": "Port42",
+  "license": "MIT",
+  "homepage": "https://port42.ai",
+  "repository": "https://github.com/gordonmattey/port42-openclaw",
+  "config": {
+    "invite": {
+      "type": "string",
+      "description": "Port42 HTTPS invite link",
+      "required": false
+    },
+    "gateway": {
+      "type": "string",
+      "description": "WebSocket URL of Port42 gateway",
+      "required": false
+    },
+    "channelId": {
+      "type": "string",
+      "description": "Port42 channel UUID",
+      "required": false
+    },
+    "encryptionKey": {
+      "type": "string",
+      "description": "Base64 AES-256 encryption key",
+      "required": false
+    },
+    "displayName": {
+      "type": "string",
+      "description": "Agent display name in Port42",
+      "required": true
+    },
+    "trigger": {
+      "type": "string",
+      "enum": ["mention", "all"],
+      "default": "mention",
+      "description": "Respond to @mentions only or all messages"
+    }
+  }
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "port42-openclaw",
+  "version": "0.1.0",
+  "description": "Port42 channel adapter for OpenClaw — bring your agents into Port42 companion computing channels",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "node --test dist/**/*.test.js"
+  },
+  "keywords": [
+    "openclaw",
+    "port42",
+    "channel",
+    "plugin",
+    "ai",
+    "companion-computing"
+  ],
+  "author": "Port42",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/gordonmattey/port42-openclaw"
+  },
+  "homepage": "https://port42.ai",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "ws": "^8.16.0"
+  },
+  "devDependencies": {
+    "@types/ws": "^8.5.10",
+    "typescript": "^5.4.0"
+  }
+}

package/src/connection.ts

@@ -0,0 +1,201 @@
+/**
+ * WebSocket connection to a Port42 gateway with reconnection.
+ */
+
+import WebSocket from 'ws';
+import {
+  type Envelope,
+  createIdentify,
+  createJoin,
+  createLeave,
+  createAck,
+  createTyping,
+  createMessage,
+} from './protocol';
+import { encrypt, decrypt } from './crypto';
+
+export interface ConnectionConfig {
+  gateway: string;
+  channelId: string;
+  senderId: string;
+  displayName: string;
+  encryptionKey: string | null;
+  trigger: 'mention' | 'all';
+  onMessage: (senderName: string, content: string, messageId: string) => void;
+  onPresence?: (onlineIds: string[]) => void;
+  onConnected?: () => void;
+  onDisconnected?: () => void;
+}
+
+export class Port42Connection {
+  private ws: WebSocket | null = null;
+  private config: ConnectionConfig;
+  private reconnectDelay = 3000;
+  private maxReconnectDelay = 30000;
+  private shouldReconnect = true;
+  private identified = false;
+
+  constructor(config: ConnectionConfig) {
+    this.config = config;
+  }
+
+  connect(): void {
+    this.shouldReconnect = true;
+    this.openSocket();
+  }
+
+  disconnect(): void {
+    this.shouldReconnect = false;
+    if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+      this.send(createLeave(this.config.channelId));
+      this.ws.close();
+    }
+    this.ws = null;
+    this.config.onDisconnected?.();
+  }
+
+  sendResponse(content: string): void {
+    if (!this.ws || this.ws.readyState !== WebSocket.OPEN) return;
+
+    if (this.config.encryptionKey) {
+      const payload = {
+        content,
+        senderName: this.config.displayName,
+        senderOwner: null,
+        replyToId: null,
+      };
+      const blob = encrypt(payload, this.config.encryptionKey);
+      this.send(createMessage(
+        this.config.channelId,
+        this.config.senderId,
+        this.config.displayName,
+        blob,
+        true,
+      ));
+    } else {
+      this.send(createMessage(
+        this.config.channelId,
+        this.config.senderId,
+        this.config.displayName,
+        content,
+        false,
+      ));
+    }
+  }
+
+  sendTyping(isTyping: boolean): void {
+    if (!this.ws || this.ws.readyState !== WebSocket.OPEN) return;
+    this.send(createTyping(this.config.channelId, this.config.senderId, isTyping));
+  }
+
+  private openSocket(): void {
+    try {
+      this.ws = new WebSocket(this.config.gateway);
+    } catch (err) {
+      console.error('[port42] Failed to create WebSocket:', err);
+      this.scheduleReconnect();
+      return;
+    }
+
+    this.ws.on('open', () => {
+      this.reconnectDelay = 3000;
+      this.identified = false;
+      this.send(createIdentify(this.config.senderId, this.config.displayName));
+    });
+
+    this.ws.on('message', (data) => {
+      try {
+        const envelope: Envelope = JSON.parse(data.toString());
+        this.handleEnvelope(envelope);
+      } catch (err) {
+        console.error('[port42] Failed to parse message:', err);
+      }
+    });
+
+    this.ws.on('close', () => {
+      this.identified = false;
+      this.config.onDisconnected?.();
+      this.scheduleReconnect();
+    });
+
+    this.ws.on('error', (err) => {
+      console.error('[port42] WebSocket error:', err.message);
+    });
+  }
+
+  private handleEnvelope(envelope: Envelope): void {
+    switch (envelope.type) {
+      case 'welcome':
+        this.identified = true;
+        this.send(createJoin(this.config.channelId));
+        this.config.onConnected?.();
+        break;
+
+      case 'message':
+        this.handleIncomingMessage(envelope);
+        break;
+
+      case 'presence':
+        if (envelope.online_ids) {
+          this.config.onPresence?.(envelope.online_ids);
+        }
+        break;
+
+      case 'error':
+        console.error('[port42] Gateway error:', envelope.error);
+        break;
+
+      case 'ack':
+        // Message delivered
+        break;
+    }
+  }
+
+  private handleIncomingMessage(envelope: Envelope): void {
+    if (!envelope.payload || !envelope.message_id) return;
+
+    // Ignore own messages
+    if (envelope.sender_id === this.config.senderId) return;
+
+    // ACK receipt
+    this.send(createAck(envelope.message_id, this.config.channelId!));
+
+    // Decrypt if needed
+    let content: string;
+    let senderName: string;
+
+    if (envelope.payload.encrypted && this.config.encryptionKey) {
+      const decrypted = decrypt(envelope.payload.content, this.config.encryptionKey);
+      if (!decrypted) {
+        console.error('[port42] Decryption failed for message:', envelope.message_id);
+        return;
+      }
+      content = decrypted.content;
+      senderName = decrypted.senderName || envelope.sender_name || 'Unknown';
+    } else {
+      content = envelope.payload.content;
+      senderName = envelope.payload.senderName || envelope.sender_name || 'Unknown';
+    }
+
+    // Check trigger rules
+    if (this.config.trigger === 'mention') {
+      const mentionPattern = new RegExp(`@${this.config.displayName}\\b`, 'i');
+      if (!mentionPattern.test(content)) return;
+    }
+
+    this.config.onMessage(senderName, content, envelope.message_id);
+  }
+
+  private send(envelope: Envelope): void {
+    if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+      this.ws.send(JSON.stringify(envelope));
+    }
+  }
+
+  private scheduleReconnect(): void {
+    if (!this.shouldReconnect) return;
+    console.log(`[port42] Reconnecting in ${this.reconnectDelay / 1000}s...`);
+    setTimeout(() => this.openSocket(), this.reconnectDelay);
+    this.reconnectDelay = Math.min(this.reconnectDelay * 2, this.maxReconnectDelay);
+  }
+}

package/src/crypto.ts

@@ -0,0 +1,49 @@
+/**
+ * AES-256-GCM encryption/decryption matching Port42's ChannelCrypto.
+ *
+ * Wire format: base64(nonce[12] + ciphertext + tag[16])
+ */
+
+import { createCipheriv, createDecipheriv, randomBytes } from 'node:crypto';
+import type { Payload } from './protocol';
+
+const ALGORITHM = 'aes-256-gcm';
+const NONCE_LENGTH = 12;
+const TAG_LENGTH = 16;
+
+export function encrypt(payload: Payload, keyBase64: string): string {
+  const key = Buffer.from(keyBase64, 'base64');
+  const nonce = randomBytes(NONCE_LENGTH);
+  const cleartext = JSON.stringify(payload);
+
+  const cipher = createCipheriv(ALGORITHM, key, nonce);
+  const encrypted = Buffer.concat([cipher.update(cleartext, 'utf8'), cipher.final()]);
+  const tag = cipher.getAuthTag();
+
+  // nonce + ciphertext + tag
+  const blob = Buffer.concat([nonce, encrypted, tag]);
+  return blob.toString('base64');
+}
+
+export function decrypt(blob: string, keyBase64: string): Payload | null {
+  try {
+    const key = Buffer.from(keyBase64, 'base64');
+    const data = Buffer.from(blob, 'base64');
+
+    if (data.length < NONCE_LENGTH + TAG_LENGTH) {
+      return null;
+    }
+
+    const nonce = data.subarray(0, NONCE_LENGTH);
+    const tag = data.subarray(data.length - TAG_LENGTH);
+    const ciphertext = data.subarray(NONCE_LENGTH, data.length - TAG_LENGTH);
+
+    const decipher = createDecipheriv(ALGORITHM, key, nonce);
+    decipher.setAuthTag(tag);
+
+    const decrypted = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+    return JSON.parse(decrypted.toString('utf8'));
+  } catch {
+    return null;
+  }
+}

package/src/index.ts

@@ -0,0 +1,165 @@
+/**
+ * Port42 channel adapter for OpenClaw.
+ *
+ * Bridges OpenClaw agents into Port42 companion computing channels.
+ * Users install with: openclaw plugins install port42-openclaw
+ * Then add a channel with a Port42 invite link.
+ */
+
+import { parseInviteLink, type InviteConfig } from './invite';
+import { Port42Connection, type ConnectionConfig } from './connection';
+import { createHash } from 'node:crypto';
+
+export interface Port42ChannelConfig {
+  invite?: string;
+  gateway?: string;
+  channelId?: string;
+  encryptionKey?: string;
+  displayName: string;
+  trigger?: 'mention' | 'all';
+}
+
+interface PluginAPI {
+  registerChannel(
+    name: string,
+    handler: ChannelHandler,
+  ): void;
+  log: {
+    info(msg: string): void;
+    error(msg: string): void;
+    debug(msg: string): void;
+  };
+}
+
+interface ChannelHandler {
+  connect(config: Port42ChannelConfig): Promise<ChannelInstance>;
+}
+
+interface ChannelInstance {
+  send(content: string): Promise<void>;
+  disconnect(): Promise<void>;
+}
+
+/**
+ * Generate a stable sender ID from the display name.
+ * This ensures the same agent gets the same ID across restarts
+ * so the gateway recognizes it as the same peer.
+ */
+function stableSenderId(displayName: string): string {
+  const hash = createHash('sha256').update(`port42-openclaw:${displayName}`).digest('hex');
+  // Format as UUID-like string for compatibility
+  return [
+    hash.slice(0, 8),
+    hash.slice(8, 12),
+    hash.slice(12, 16),
+    hash.slice(16, 20),
+    hash.slice(20, 32),
+  ].join('-');
+}
+
+/**
+ * Resolve config from either an invite link or explicit fields.
+ */
+function resolveConfig(config: Port42ChannelConfig): {
+  gateway: string;
+  channelId: string;
+  encryptionKey: string | null;
+} {
+  if (config.invite) {
+    const parsed = parseInviteLink(config.invite);
+    return {
+      gateway: config.gateway || parsed.gateway,
+      channelId: config.channelId || parsed.channelId,
+      encryptionKey: config.encryptionKey || parsed.encryptionKey,
+    };
+  }
+
+  if (!config.gateway || !config.channelId) {
+    throw new Error('Port42 channel requires either an invite link or explicit gateway + channelId');
+  }
+
+  return {
+    gateway: config.gateway,
+    channelId: config.channelId,
+    encryptionKey: config.encryptionKey || null,
+  };
+}
+
+/**
+ * OpenClaw plugin entry point.
+ */
+export function register(api: PluginAPI): void {
+  api.registerChannel('port42', {
+    async connect(config: Port42ChannelConfig): Promise<ChannelInstance> {
+      const resolved = resolveConfig(config);
+      const senderId = stableSenderId(config.displayName);
+      const trigger = config.trigger || 'mention';
+
+      api.log.info(`Connecting to Port42 channel ${resolved.channelId} as "${config.displayName}"`);
+
+      return new Promise<ChannelInstance>((resolve, reject) => {
+        let messageHandler: ((senderName: string, content: string, messageId: string) => void) | null = null;
+
+        const connection = new Port42Connection({
+          gateway: resolved.gateway,
+          channelId: resolved.channelId,
+          senderId,
+          displayName: config.displayName,
+          encryptionKey: resolved.encryptionKey,
+          trigger,
+
+          onMessage(senderName, content, messageId) {
+            if (messageHandler) {
+              messageHandler(senderName, content, messageId);
+            }
+          },
+
+          onConnected() {
+            api.log.info(`Connected to Port42 as "${config.displayName}"`);
+            resolve({
+              async send(content: string) {
+                connection.sendTyping(true);
+                // Small delay so typing indicator shows before response
+                await new Promise((r) => setTimeout(r, 100));
+                connection.sendResponse(content);
+                connection.sendTyping(false);
+              },
+
+              async disconnect() {
+                connection.disconnect();
+                api.log.info(`Disconnected from Port42`);
+              },
+            });
+          },
+
+          onDisconnected() {
+            api.log.debug('Port42 connection lost');
+          },
+
+          onPresence(onlineIds) {
+            api.log.debug(`Port42 presence: ${onlineIds.length} online`);
+          },
+        });
+
+        // Wire up the message handler for OpenClaw to receive inbound messages
+        messageHandler = (senderName, content, _messageId) => {
+          api.log.debug(`[${senderName}]: ${content.slice(0, 100)}`);
+        };
+
+        connection.connect();
+
+        // Timeout if we can't connect within 15 seconds
+        setTimeout(() => {
+          reject(new Error('Port42 connection timeout (15s)'));
+        }, 15000);
+      });
+    },
+  });
+}
+
+// Re-export modules for standalone use
+export { parseInviteLink } from './invite';
+export { Port42Connection } from './connection';
+export type { ConnectionConfig } from './connection';
+export type { InviteConfig } from './invite';
+export { encrypt, decrypt } from './crypto';

package/src/invite.ts

@@ -0,0 +1,31 @@
+/**
+ * Parse Port42 HTTPS invite links into connection config.
+ *
+ * Invite format:
+ * https://<host>/invite?id=<channel-uuid>&name=<channel-name>&key=<url-encoded-base64-aes-key>
+ */
+
+export interface InviteConfig {
+  gateway: string;
+  channelId: string;
+  channelName: string;
+  encryptionKey: string | null;
+}
+
+export function parseInviteLink(invite: string): InviteConfig {
+  const url = new URL(invite);
+
+  const channelId = url.searchParams.get('id');
+  if (!channelId) {
+    throw new Error('Invite link missing channel id (id= parameter)');
+  }
+
+  const channelName = url.searchParams.get('name') || 'unknown';
+  const encryptionKey = url.searchParams.get('key') || null;
+
+  // Derive WebSocket URL from the HTTPS host
+  const protocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
+  const gateway = `${protocol}//${url.host}/ws`;
+
+  return { gateway, channelId, channelName, encryptionKey };
+}

package/src/protocol.ts

@@ -0,0 +1,106 @@
+/**
+ * Port42 gateway WebSocket protocol types.
+ */
+
+export type EnvelopeType =
+  | 'identify'
+  | 'welcome'
+  | 'join'
+  | 'leave'
+  | 'message'
+  | 'ack'
+  | 'presence'
+  | 'typing'
+  | 'error';
+
+export interface Envelope {
+  type: EnvelopeType;
+  channel_id?: string;
+  sender_id?: string;
+  sender_name?: string;
+  message_id?: string;
+  payload?: Payload;
+  timestamp?: number;
+  error?: string;
+  online_ids?: string[];
+  status?: 'online' | 'offline';
+  companion_ids?: string[];
+}
+
+export interface Payload {
+  content: string;
+  senderName?: string;
+  senderOwner?: string | null;
+  replyToId?: string | null;
+  encrypted?: boolean;
+}
+
+export function createIdentify(senderId: string, senderName: string): Envelope {
+  return {
+    type: 'identify',
+    sender_id: senderId,
+    sender_name: senderName,
+  };
+}
+
+export function createJoin(channelId: string, companionIds: string[] = []): Envelope {
+  return {
+    type: 'join',
+    channel_id: channelId,
+    companion_ids: companionIds,
+  };
+}
+
+export function createLeave(channelId: string): Envelope {
+  return {
+    type: 'leave',
+    channel_id: channelId,
+  };
+}
+
+export function createMessage(
+  channelId: string,
+  senderId: string,
+  senderName: string,
+  content: string,
+  encrypted: boolean = false,
+): Envelope {
+  return {
+    type: 'message',
+    channel_id: channelId,
+    sender_id: senderId,
+    sender_name: senderName,
+    message_id: crypto.randomUUID(),
+    payload: {
+      content,
+      senderName: encrypted ? '' : senderName,
+      senderOwner: null,
+      replyToId: null,
+      encrypted,
+    },
+    timestamp: Date.now(),
+  };
+}
+
+export function createAck(messageId: string, channelId: string): Envelope {
+  return {
+    type: 'ack',
+    message_id: messageId,
+    channel_id: channelId,
+  };
+}
+
+export function createTyping(
+  channelId: string,
+  senderId: string,
+  isTyping: boolean,
+): Envelope {
+  return {
+    type: 'typing',
+    channel_id: channelId,
+    sender_id: senderId,
+    payload: {
+      content: isTyping ? 'typing' : 'stopped',
+    },
+  };
+}

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "commonjs",
+    "lib": ["ES2022"],
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"]
+}