@xns-cloud/relayer-mcp 0.3.0

package/src/lib/oidcAuth.js

@@ -0,0 +1,256 @@
+'use strict';
+
+const crypto = require('crypto');
+const http = require('http');
+const { createHttpClient } = require('./httpClient');
+
+const DEFAULT_KEYCLOAK_URL = 'https://auth.xns.tech/auth';
+const DEFAULT_REALM = 'scprime';
+const DEFAULT_CLIENT_ID = 'relayer-native';
+
+/**
+ * OIDC Authorization Code + PKCE (S256) token acquisition.
+ *
+ * Performs a browser-based OIDC sign-in flow:
+ * 1. Generate PKCE verifier + S256 challenge
+ * 2. Start a 127.0.0.1 loopback HTTP listener on an ephemeral port
+ * 3. Build the authorize URL and open the browser (or return the URL)
+ * 4. Capture the authorization code on the redirect
+ * 5. Exchange code for access_token + refresh_token
+ *
+ * Interface is kept clean for future extraction to @xns-cloud/relayer-auth (CLI reuse).
+ *
+ * @param {object} opts
+ * @param {string} [opts.clientId] - Keycloak public client ID
+ * @param {string} [opts.realm] - Keycloak realm
+ * @param {string} [opts.keycloakUrl] - Base Keycloak URL
+ * @param {string[]} [opts.scopes] - OIDC scopes
+ * @param {object} [opts.httpClient] - Injected HTTP client (testing)
+ * @param {function} [opts.openBrowser] - Injected browser opener (testing)
+ * @param {function} [opts.createServer] - Injected http.createServer (testing)
+ * @returns {Promise<{access_token: string, expires_at: number, refresh_token: string, authorize_url: string}>}
+ */
+async function acquireToken(opts = {}) {
+    const clientId = opts.clientId || DEFAULT_CLIENT_ID;
+    const realm = opts.realm || DEFAULT_REALM;
+    const keycloakUrl = opts.keycloakUrl || DEFAULT_KEYCLOAK_URL;
+    const scopes = opts.scopes || ['openid'];
+    const httpClient = opts.httpClient || createHttpClient({ timeout: 15000 });
+    const openBrowser = opts.openBrowser || defaultOpenBrowser;
+    const _createServer = opts.createServer || http.createServer.bind(http);
+
+    // 1. PKCE verifier + S256 challenge
+    const verifier = generateVerifier();
+    const challenge = generateChallenge(verifier);
+
+    // 2. Loopback listener on ephemeral port (R7: platform-agnostic bind)
+    const { code, redirectUri } = await captureAuthCode({
+        clientId,
+        realm,
+        keycloakUrl,
+        scopes,
+        verifier,
+        challenge,
+        openBrowser,
+        createServer: _createServer,
+    });
+
+    // 5. Exchange code for tokens
+    const tokenUrl = `${keycloakUrl}/realms/${realm}/protocol/openid-connect/token`;
+    const body = new URLSearchParams({
+        grant_type: 'authorization_code',
+        client_id: clientId,
+        code,
+        redirect_uri: redirectUri,
+        code_verifier: verifier,
+    }).toString();
+
+    const { status, data } = await httpClient.post(tokenUrl, body, {
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    });
+
+    if (status !== 200) {
+        throw new Error(`Token exchange failed (HTTP ${status}): ${JSON.stringify(data)}`);
+    }
+
+    return {
+        access_token: data.access_token,
+        refresh_token: data.refresh_token,
+        expires_at: Date.now() + (data.expires_in * 1000),
+        authorize_url: undefined, // already consumed
+    };
+}
+
+/**
+ * Refresh an access token using a refresh_token.
+ *
+ * @param {object} opts
+ * @param {string} opts.refreshToken
+ * @param {string} [opts.clientId]
+ * @param {string} [opts.realm]
+ * @param {string} [opts.keycloakUrl]
+ * @param {object} [opts.httpClient]
+ * @returns {Promise<{access_token: string, expires_at: number, refresh_token: string}>}
+ */
+async function refreshToken(opts = {}) {
+    const clientId = opts.clientId || DEFAULT_CLIENT_ID;
+    const realm = opts.realm || DEFAULT_REALM;
+    const keycloakUrl = opts.keycloakUrl || DEFAULT_KEYCLOAK_URL;
+    const httpClient = opts.httpClient || createHttpClient({ timeout: 15000 });
+
+    const tokenUrl = `${keycloakUrl}/realms/${realm}/protocol/openid-connect/token`;
+    const body = new URLSearchParams({
+        grant_type: 'refresh_token',
+        client_id: clientId,
+        refresh_token: opts.refreshToken,
+    }).toString();
+
+    const { status, data } = await httpClient.post(tokenUrl, body, {
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    });
+
+    if (status !== 200) {
+        throw new Error(`Token refresh failed (HTTP ${status}): ${JSON.stringify(data)}`);
+    }
+
+    return {
+        access_token: data.access_token,
+        refresh_token: data.refresh_token,
+        expires_at: Date.now() + (data.expires_in * 1000),
+    };
+}
+
+/**
+ * Generate a PKCE code verifier (43-128 chars, URL-safe base64).
+ * @returns {string}
+ */
+function generateVerifier() {
+    return crypto.randomBytes(32).toString('base64url');
+}
+
+/**
+ * Generate a PKCE S256 challenge from a verifier.
+ * @param {string} verifier
+ * @returns {string}
+ */
+function generateChallenge(verifier) {
+    return crypto.createHash('sha256').update(verifier).digest('base64url');
+}
+
+/**
+ * Start a loopback HTTP server, open the browser to the authorize URL,
+ * and wait for the authorization code redirect.
+ *
+ * @param {object} opts
+ * @returns {Promise<{code: string, redirectUri: string}>}
+ */
+function captureAuthCode(opts) {
+    const { clientId, realm, keycloakUrl, scopes, verifier, challenge, openBrowser, createServer } = opts;
+
+    return new Promise((resolve, reject) => {
+        let timeoutHandle;
+        let capturedPort;
+        let expectedState;
+
+        const srv = createServer((req, res) => {
+            const url = new URL(req.url, `http://127.0.0.1`);
+
+            const error = url.searchParams.get('error');
+            if (error) {
+                res.writeHead(400, { 'Content-Type': 'text/html' });
+                res.end('<html><body><h1>Authentication failed</h1><p>You can close this window.</p></body></html>');
+                clearTimeout(timeoutHandle);
+                srv.close();
+                return reject(new Error(`OIDC error: ${error} — ${url.searchParams.get('error_description') || ''}`));
+            }
+
+            const code = url.searchParams.get('code');
+            if (!code) {
+                res.writeHead(400, { 'Content-Type': 'text/html' });
+                res.end('<html><body><h1>Missing authorization code</h1></body></html>');
+                return; // Don't close server — wait for the real redirect
+            }
+
+            // R5-STATE-1: Validate OIDC state parameter to prevent CSRF
+            const returnedState = url.searchParams.get('state');
+            if (returnedState !== expectedState) {
+                res.writeHead(400, { 'Content-Type': 'text/html' });
+                res.end('<html><body><h1>Invalid state parameter</h1><p>Possible CSRF attack. Please try again.</p></body></html>');
+                clearTimeout(timeoutHandle);
+                srv.close();
+                return reject(new Error('OIDC callback state mismatch — possible CSRF. Please try again.'));
+            }
+
+            res.writeHead(200, { 'Content-Type': 'text/html' });
+            res.end('<html><body><h1>Authentication successful</h1><p>You can close this window and return to the agent.</p></body></html>');
+            clearTimeout(timeoutHandle);
+
+            // Capture redirect URI from the port stored in listen callback
+            // BEFORE calling srv.close() — after close, srv.address() may return null
+            const redirectUri = `http://127.0.0.1:${capturedPort}/callback`;
+            srv.close();
+            resolve({ code, redirectUri });
+        });
+
+        // Bind to 127.0.0.1:0 (ephemeral port) — R7 platform-agnostic
+        srv.listen(0, '127.0.0.1', () => {
+            capturedPort = srv.address().port;
+            const redirectUri = `http://127.0.0.1:${capturedPort}/callback`;
+            expectedState = crypto.randomBytes(16).toString('hex');
+
+            const params = new URLSearchParams({
+                response_type: 'code',
+                client_id: clientId,
+                redirect_uri: redirectUri,
+                scope: scopes.join(' '),
+                code_challenge: challenge,
+                code_challenge_method: 'S256',
+                state: expectedState,
+            });
+
+            const authorizeUrl = `${keycloakUrl}/realms/${realm}/protocol/openid-connect/auth?${params}`;
+
+            // Open browser or return URL for the agent to present
+            openBrowser(authorizeUrl).catch(() => {
+                // If browser open fails, the authorize_url is still available
+            });
+        });
+
+        // Timeout: 5 minutes for user to complete browser sign-in
+        timeoutHandle = setTimeout(() => {
+            srv.close();
+            reject(new Error('OIDC sign-in timed out after 5 minutes. Please try again.'));
+        }, 300000);
+    });
+}
+
+/**
+ * Default browser opener — platform-aware.
+ * Uses execFile (not exec) to avoid shell interpolation of the URL.
+ * @param {string} url
+ * @returns {Promise<void>}
+ */
+function defaultOpenBrowser(url) {
+    const { execFile } = require('child_process');
+    return new Promise((resolve, reject) => {
+        const platform = process.platform;
+        let cmd, args;
+        if (platform === 'darwin') {
+            cmd = 'open';
+            args = [url];
+        } else if (platform === 'win32') {
+            cmd = 'cmd';
+            args = ['/c', 'start', '', url];
+        } else {
+            cmd = 'xdg-open';
+            args = [url];
+        }
+
+        execFile(cmd, args, (err) => {
+            if (err) return reject(err);
+            resolve();
+        });
+    });
+}
+
+module.exports = { acquireToken, refreshToken, generateVerifier, generateChallenge };

package/src/lib/pollUntil.js

@@ -0,0 +1,31 @@
+'use strict';
+
+/**
+ * Poll a check function at a fixed interval until it resolves truthy
+ * or the timeout elapses.
+ *
+ * @param {object} opts
+ * @param {function(): Promise<*>} opts.fn - Async check function. Return truthy to stop.
+ * @param {number} opts.intervalMs - Poll interval in ms
+ * @param {number} opts.timeoutMs - Total timeout in ms
+ * @param {function} [opts.sleep] - Injectable sleep (testing). Default: real setTimeout.
+ * @returns {Promise<{result: *, timedOut: boolean}>}
+ */
+async function pollUntil({ fn, intervalMs, timeoutMs, sleep }) {
+    const _sleep = sleep || ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const deadline = Date.now() + timeoutMs;
+
+    while (Date.now() < deadline) {
+        const result = await fn();
+        if (result) {
+            return { result, timedOut: false };
+        }
+        const remaining = deadline - Date.now();
+        if (remaining <= 0) break;
+        await _sleep(Math.min(intervalMs, remaining));
+    }
+
+    return { result: null, timedOut: true };
+}
+
+module.exports = { pollUntil };

package/src/lib/s3Client.js

@@ -0,0 +1,73 @@
+'use strict';
+
+const {
+    S3Client,
+    CreateBucketCommand,
+    PutObjectCommand,
+    GetObjectCommand,
+} = require('@aws-sdk/client-s3');
+
+/**
+ * S3 client for verify_storage (Tool 10).
+ * Targets localhost:9000 plain HTTP with forcePathStyle.
+ *
+ * @param {object} [options]
+ * @param {string} [options.endpoint] - S3 endpoint (default: http://localhost:9000)
+ * @param {string} [options.region] - AWS region (default: us-east-1)
+ * @param {string} options.accessKeyId
+ * @param {string} options.secretAccessKey
+ * @param {object} [options.s3Client] - Injected S3Client instance (testing)
+ */
+function createS3Client(options = {}) {
+    const client = options.s3Client || new S3Client({
+        endpoint: options.endpoint || 'http://localhost:9000',
+        region: options.region || 'us-east-1',
+        forcePathStyle: true,
+        credentials: {
+            accessKeyId: options.accessKeyId,
+            secretAccessKey: options.secretAccessKey,
+        },
+    });
+
+    return {
+        /**
+         * @param {string} bucket
+         * @returns {Promise<void>}
+         */
+        async createBucket(bucket) {
+            await client.send(new CreateBucketCommand({ Bucket: bucket }));
+        },
+
+        /**
+         * @param {string} bucket
+         * @param {string} key
+         * @param {Buffer|string} body
+         * @returns {Promise<void>}
+         */
+        async putObject(bucket, key, body) {
+            await client.send(new PutObjectCommand({
+                Bucket: bucket,
+                Key: key,
+                Body: body,
+            }));
+        },
+
+        /**
+         * @param {string} bucket
+         * @param {string} key
+         * @returns {Promise<string>}
+         */
+        async getObject(bucket, key) {
+            const resp = await client.send(new GetObjectCommand({
+                Bucket: bucket,
+                Key: key,
+            }));
+            return resp.Body.transformToString();
+        },
+
+        /** Expose the raw client for advanced use */
+        client,
+    };
+}
+
+module.exports = { createS3Client };

package/src/lib/tokenState.js

@@ -0,0 +1,24 @@
+'use strict';
+
+/**
+ * Shared OIDC token state — single module-level cache shared by
+ * getHostTags and configureVpd (and any future authenticated tools).
+ *
+ * Eliminates duplicate browser sign-ins caused by independent
+ * `let tokenState = null` declarations in each tool module.
+ */
+let tokenState = null;
+
+function get() {
+    return tokenState;
+}
+
+function set(state) {
+    tokenState = state;
+}
+
+function clear() {
+    tokenState = null;
+}
+
+module.exports = { get, set, clear };

package/src/templates/docker-compose.yml

@@ -0,0 +1,27 @@
+# Bundled by @xns-cloud/relayer-mcp — the documented released XNS Relayer install.
+# Source of truth: https://xns.tech/docs/windows-ui/ (Docker Hub scprime/xns-relayer).
+#
+# Pre-release: pinned to the :beta channel so alpha/beta testers exercise the
+# current Relayer agentically. Flip this one tag to :stable at general release.
+#
+# A first-time user no longer hand-writes this file or the .env — install_relayer
+# writes both. Differences from the hand-written docs compose, by design:
+#   - data lives in ./data (relative to this file) instead of a Windows-only
+#     C:\XNS-Relayer bind, so the same file works on Windows, macOS, and Linux.
+#   - SMB ports 139/445 are intentionally NOT exposed: 445 is held by Windows
+#     SMB on consumer hosts and would fail the install. S3 onboarding uses :9000.
+#   - pull_policy: always so `docker compose up -d` fetches the current :beta
+#     image without a separate `docker compose pull` step.
+services:
+  xns:
+    container_name: xns-relayer
+    image: scprime/xns-relayer:beta
+    pull_policy: always
+    restart: unless-stopped
+    volumes:
+      - ./data:/relayer
+    ports:
+      - ${UI_PORT:-8888}:8888
+      - ${MINIO_PORT:-9000}:9000
+    env_file:
+      - .env

package/src/tools/checkClaimStatus.js

@@ -0,0 +1,154 @@
+'use strict';
+
+const { z } = require('zod');
+const { createHttpClient } = require('../lib/httpClient');
+const { pollUntil } = require('../lib/pollUntil');
+
+const RELAYER_UI_BASE = 'http://localhost:8888';
+const POLL_INTERVAL_MS = 10000;  // 10s (AC-15)
+
+/**
+ * Tool 7: check_claim_status
+ * AC-15: poll every 10s; surface STATE_1->2->3; auto-proceed on STATE_3.
+ * AC-15a: 402 → {continue_polling:false, message}, no TTL loop.
+ * AC-16: TTL expiry (no 402) → "session expired" + new start_claim.
+ *
+ * Consumes relayer-ui: GET /api/v1/claim/status?claim_id=...
+ *   → {state:'STATE_1'|'STATE_2'|'STATE_3', detail, installation_id?, claimed_at?}
+ *   → 402: payment method required
+ *   → 404: claim not found (expired or invalid)
+ */
+module.exports = function registerCheckClaimStatus(server, options = {}) {
+    const http = options.httpClient || createHttpClient(options);
+    const relayerUiBase = options.relayerUiBase || RELAYER_UI_BASE;
+    const pollInterval = options.pollIntervalMs ?? POLL_INTERVAL_MS;
+    const sleep = options.sleep;
+
+    server.tool(
+        'check_claim_status',
+        'Poll the status of a claim session. Checks every 10 seconds. States: STATE_1 (pending — user has not yet opened the claim URL), STATE_2 (in progress — user is completing the claim in browser), STATE_3 (completed — claim successful). Automatically proceeds when STATE_3 is reached.',
+        {
+            claim_id: z.string().describe('The claim_id returned by start_claim'),
+            timeout_ms: z.number().optional().default(600000).describe('Maximum time to poll in milliseconds (default: 10 minutes)'),
+        },
+        async ({ claim_id, timeout_ms }) => {
+            try {
+                const checkOnce = async () => {
+                    const { status, data } = await http.get(
+                        `${relayerUiBase}/api/v1/claim/status?claim_id=${encodeURIComponent(claim_id)}`,
+                    );
+
+                    // AC-15a: 402 → stop, no loop
+                    if (status === 402) {
+                        return {
+                            done: true,
+                            stop: true,
+                            result: {
+                                success: false,
+                                continue_polling: false,
+                                message: 'A payment method is required before the claim can complete. Please add a payment method at console.xns.tech, then run start_claim again.',
+                            },
+                        };
+                    }
+
+                    // AC-16: 404 → expired
+                    if (status === 404) {
+                        return {
+                            done: true,
+                            result: {
+                                success: false,
+                                message: 'Claim session has expired or was not found. Run start_claim to create a new claim session.',
+                                expired: true,
+                            },
+                        };
+                    }
+
+                    if (status >= 400) {
+                        return {
+                            done: true,
+                            result: {
+                                success: false,
+                                error: data.error || `Claim status check failed (HTTP ${status}).`,
+                            },
+                        };
+                    }
+
+                    const state = data.state;
+
+                    if (state === 'STATE_3') {
+                        return {
+                            done: true,
+                            result: {
+                                success: true,
+                                message: 'Claim completed successfully. The Relayer is now linked to your account.',
+                                state: 'STATE_3',
+                                installation_id: data.installation_id,
+                                claimed_at: data.claimed_at,
+                            },
+                        };
+                    }
+
+                    // STATE_1 or STATE_2 — still in progress
+                    const stateMessages = {
+                        STATE_1: 'Waiting for the user to open the claim URL in a browser.',
+                        STATE_2: 'Claim is in progress — the user is completing the browser flow.',
+                    };
+
+                    return {
+                        done: false,
+                        result: {
+                            success: false,
+                            state,
+                            message: stateMessages[state] || `Claim in state: ${state}`,
+                            detail: data.detail,
+                        },
+                    };
+                };
+
+                const { result, timedOut } = await pollUntil({
+                    fn: async () => {
+                        const check = await checkOnce();
+                        if (check.done) return check.result;
+                        return null;
+                    },
+                    intervalMs: pollInterval,
+                    timeoutMs: timeout_ms,
+                    sleep,
+                });
+
+                if (timedOut) {
+                    // AC-16: TTL expiry
+                    return {
+                        content: [{
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: false,
+                                message: 'Claim status polling timed out. The claim session may have expired. Run start_claim to create a new claim session.',
+                                expired: true,
+                            }, null, 2),
+                        }],
+                    };
+                }
+
+                return {
+                    content: [{
+                        type: 'text',
+                        text: JSON.stringify(result, null, 2),
+                    }],
+                    isError: (result.success === false && result.continue_polling !== false) ? true : undefined,
+                };
+            } catch (err) {
+                return {
+                    content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: false,
+                            error: `Claim status check failed: ${err.message}`,
+                        }),
+                    }],
+                    isError: true,
+                };
+            }
+        },
+    );
+};