@realtimex/rtxexec 0.1.0 → 0.2.0

package/README.md

@@ -41,3 +41,40 @@ when the installed launcher is a .cmd/.bat file. Shell pipelines must be compose
 explicitly; the wrapper does not interpret shell syntax.
 
 `npm test` runs isolated fixtures. `npm pack --dry-run` validates package contents.
+
+
+## Browser Login credentials (0.2.0)
+
+Create a **Login** in RealTimeX Settings > Secrets (encrypted username/password,
+login URL and exact allowed origins). Management belongs to the moderator CLI;
+rtxexec only uses credentials. Browser operations require Node.js 22 or newer.
+
+Prepare the page using agent-browser on your existing RealTimeX browser. Then:
+
+```sh
+rtxexec browser-tabs --cdp 9235
+rtxexec browser-login secret://company-login --cdp 9235 --tab <target-id> \
+  --username-selector '#username' --password-selector '#password' \
+  --submit-selector 'button[type=submit]'
+```
+
+Use the full target ID from `browser-tabs`, not agent-browser's `t1`/`t2` alias.
+The command never navigates or chooses a tab automatically. Each CSS selector must
+match exactly one visible top-level form control. Iframe forms are not supported.
+For two-step logins, specify only the username selector first, then prepare the
+password step and run again with only its selector. Omit submit to fill only.
+A `filled` or `submitted` result does not prove authentication: verify a non-secret
+success state separately. MFA and CAPTCHA stay in the normal browser workflow.
+
+This works with agent-browser 0.27.0 because it uses the local CDP connection
+instead of unsupported credential-provider flags. Values are passed as CDP
+arguments in an isolated execution context, never inserted into JavaScript source,
+saved in another vault, or printed in normal output. Scope, enabled state and exact
+origin are checked before resolution; the form's origin/action is rechecked during
+filling. History records resolution with browser origin/target and terminal context,
+not an assertion that login succeeded.
+
+The destination/browser necessarily receives the values. Do not take snapshots,
+screenshots, recordings, DOM-value reads, or network traces while credentials are
+present. A page may display a username after login. This reduces accidental exposure;
+it does not prevent intentional local extraction or malicious website behavior.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@realtimex/rtxexec",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Run commands with secrets from the RealTimeX app vault",
   "type": "module",
   "bin": { "rtxexec": "bin/rtxexec.js" },

package/src/browser.js

@@ -0,0 +1,133 @@
+import { UsageError } from './error.js';
+import { resolveSecrets } from './client.js';
+
+export function parseBrowserArguments(argv) {
+  const command = argv[0];
+  const options = {};
+  let reference;
+  let i = 1;
+  if (command === 'browser-login') reference = argv[i++];
+  const allowed = command === 'browser-tabs' ? ['cdp'] : ['cdp', 'tab', 'username-selector', 'password-selector', 'submit-selector'];
+  for (; i < argv.length; i += 2) {
+    const key = argv[i]?.replace(/^--/, '');
+    if (!argv[i]?.startsWith('--') || !allowed.includes(key) || options[key] !== undefined || !argv[i + 1] || argv[i + 1].startsWith('--')) throw new UsageError('Invalid browser option. See rtxexec --help.');
+    options[key] = argv[i + 1];
+  }
+  if (!/^\d{1,5}$/.test(options.cdp || '') || Number(options.cdp) < 1 || Number(options.cdp) > 65535) throw new UsageError('Provide a local CDP port with --cdp.');
+  if (command === 'browser-login' && (!reference?.startsWith('secret://') || !/^[a-zA-Z0-9_-]{1,128}$/.test(options.tab || '') || (!options['username-selector'] && !options['password-selector']))) throw new UsageError('Provide a secret reference, --tab from browser-tabs, and at least one username/password selector.');
+  return { command, reference, ...options };
+}
+
+export async function browserTargets(port, fetchImpl = fetch) {
+  const response = await fetchImpl(`http://127.0.0.1:${port}/json/list`, { redirect: 'error', signal: AbortSignal.timeout(5000) });
+  if (!response.ok) throw new UsageError('Could not list browser tabs.');
+  let targets;
+  try { targets = await response.json(); } catch { throw new UsageError('Invalid CDP target response.'); }
+  if (!Array.isArray(targets)) throw new UsageError('Invalid CDP target response.');
+  return targets.filter((target) => {
+    try {
+      const url = new URL(target.url);
+      return target.type === 'page' && ['http:', 'https:'].includes(url.protocol) && url.pathname !== '/cli-browser/index.html';
+    } catch { return false; }
+  });
+}
+
+export async function connectCdp(address, port, WebSocketImpl = globalThis.WebSocket) {
+  if (!WebSocketImpl) throw new UsageError('Browser login requires Node.js 22 or newer.');
+  const url = new URL(address);
+  if (url.protocol !== 'ws:' || !['localhost', '127.0.0.1', '[::1]'].includes(url.hostname) || url.port !== String(Number(port)) || url.username || url.password) throw new UsageError('CDP must use the selected local browser port.');
+  const socket = new WebSocketImpl(url);
+  const pending = new Map(); let nextId = 0;
+  const rejectAll = () => { for (const entry of pending.values()) { clearTimeout(entry.timer); entry.reject(new Error('CDP connection ended')); } pending.clear(); };
+  socket.addEventListener('close', rejectAll);
+  socket.addEventListener('error', rejectAll);
+  socket.addEventListener('message', ({ data }) => {
+    let message; try { message = JSON.parse(data); } catch { return; }
+    const entry = pending.get(message.id); if (!entry) return;
+    pending.delete(message.id); clearTimeout(entry.timer);
+    if (message.error) entry.reject(new Error('CDP operation failed'));
+    else entry.resolve(message.result);
+  });
+  await new Promise((resolve, reject) => {
+    const timer = setTimeout(() => { socket.close(); reject(new Error('CDP connection timeout')); }, 5000);
+    socket.addEventListener('open', () => { clearTimeout(timer); resolve(); }, { once: true });
+    socket.addEventListener('error', () => { clearTimeout(timer); reject(new Error('CDP connection failed')); }, { once: true });
+  });
+  return {
+    send(method, params = {}) {
+      return new Promise((resolve, reject) => {
+        const id = ++nextId;
+        const timer = setTimeout(() => { pending.delete(id); reject(new Error('CDP operation timeout')); }, 10000);
+        pending.set(id, { resolve, reject, timer });
+        socket.send(JSON.stringify({ id, method, params }));
+      });
+    },
+    close() { rejectAll(); socket.close(); },
+  };
+}
+
+// Fixed code executed in an isolated world. Values travel only as CDP arguments,
+// never interpolated into source or returned to the caller. Top-level forms only.
+export function fillLogin(username, password, selectors, expectedOrigin) {
+  const sameOrigin = () => location.origin === expectedOrigin;
+  const find = (selector) => { if (!selector) return null; const matches = document.querySelectorAll(selector); return matches.length === 1 ? matches[0] : null; };
+  const user = find(selectors.username); const pass = find(selectors.password); const submit = find(selectors.submit);
+  const fields = [[user, username, selectors.username], [pass, password, selectors.password]];
+  const safeForm = (element) => !element?.form || new URL(element.form.action || location.href).origin === expectedOrigin;
+  const usable = (element) => {
+    if (!element || element.disabled || element.matches(':disabled') || element.getClientRects().length === 0) return false;
+    const style = getComputedStyle(element);
+    if (style.visibility !== 'visible') return false;
+    for (let node = element; node; node = node.parentElement) {
+      if (Number(getComputedStyle(node).opacity) === 0) return false;
+    }
+    return true;
+  };
+  if (!sameOrigin()) return { error: 'origin' };
+  for (const [element, , selector] of fields) {
+    if (!selector) continue;
+    if (!(element instanceof HTMLInputElement) || element.readOnly || !usable(element) || !safeForm(element)) return { error: 'field' };
+  }
+  if (pass && pass.type !== 'password') return { error: 'password-field' };
+  if (selectors.submit && (!usable(submit) || !safeForm(submit) || (submit.formAction && new URL(submit.formAction).origin !== expectedOrigin))) return { error: 'submit' };
+  const setter = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, 'value').set;
+  for (const [element, value, selector] of fields) {
+    if (!selector) continue;
+    if (!sameOrigin() || !element.isConnected || !usable(element) || element.readOnly || (element === pass && element.type !== "password") || !safeForm(element)) return { error: 'changed' };
+    setter.call(element, value);
+    element.dispatchEvent(new Event('input', { bubbles: true }));
+    element.dispatchEvent(new Event('change', { bubbles: true }));
+  }
+  if (submit) {
+    if (!sameOrigin() || !submit.isConnected || !usable(submit) || !safeForm(submit) || (submit.formAction && new URL(submit.formAction).origin !== expectedOrigin)) return { error: 'changed' };
+    submit.click();
+  }
+  return { status: submit ? 'submitted' : 'filled' };
+}
+
+export async function runBrowser(plan, env, { targets = browserTargets, connect = connectCdp, resolver = resolveSecrets } = {}) {
+  const pages = await targets(plan.cdp);
+  if (plan.command === 'browser-tabs') return { tabs: pages.map(({ id, url }) => { const clean = new URL(url); clean.search = ''; clean.hash = ''; clean.username = ''; clean.password = ''; return { id, url: clean.href }; }) };
+  const target = pages.find(({ id }) => id === plan.tab);
+  if (!target) throw new UsageError('Selected browser tab is unavailable. Run browser-tabs again.');
+  const cdp = await connect(target.webSocketDebuggerUrl, plan.cdp);
+  try {
+    const { frameTree } = await cdp.send('Page.getFrameTree');
+    let origin;
+    try {
+      const url = new URL(frameTree?.frame?.url);
+      if (!['http:', 'https:'].includes(url.protocol)) throw new Error();
+      origin = url.origin;
+    } catch { throw new UsageError('Selected page is not ready. Wait for navigation and run browser-tabs again.'); }
+    const { executionContextId } = await cdp.send('Page.createIsolatedWorld', { frameId: frameTree.frame.id, worldName: 'rtxexec-login' });
+    const values = await resolver({ references: [plan.reference], command: 'rtxexec', browser: { origin, targetId: target.id } }, env);
+    const credential = values[0];
+    if (typeof credential?.username !== 'string' || !credential.username || typeof credential.password !== 'string' || !credential.password || !Array.isArray(credential.allowedOrigins) || !credential.allowedOrigins.includes(origin)) throw new UsageError('RealTimeX did not authorize a Login credential for this website.');
+    const result = await cdp.send('Runtime.callFunctionOn', {
+      executionContextId, functionDeclaration: fillLogin.toString(), returnByValue: true,
+      arguments: [credential.username, credential.password, { username: plan['username-selector'], password: plan['password-selector'], submit: plan['submit-selector'] }, origin].map((value) => ({ value })),
+    });
+    if (result.exceptionDetails || !['filled', 'submitted'].includes(result.result?.value?.status)) throw new UsageError('Login was not completed. Check the selected page, origin and visible form selectors; values were not printed.');
+    return { status: result.result.value.status, targetId: target.id, origin };
+  } finally { cdp.close(); }
+}

package/src/cli.js

@@ -1,3 +1,4 @@
+import { parseBrowserArguments, runBrowser } from "./browser.js";
 import { UsageError } from "./error.js";
 import { spawn } from 'node:child_process';
 import { constants } from 'node:os';
@@ -14,6 +15,14 @@ Usage: rtxexec [bindings] -- executable [arguments]
   --secret alias=secret://name   Substitute {{alias}} inside argument values
   --stdin secret://name          Write the exact value to child stdin, then close it
 
+Browser use (Node.js 22+, existing local CDP browser):
+  rtxexec browser-tabs --cdp <port>
+  rtxexec browser-login secret://name --cdp <port> --tab <CDP-target-id>
+    --username-selector <css> --password-selector <css> [--submit-selector <css>]
+  Omit either field selector for a multi-step login. No navigation or screenshots.
+  Supports top-level forms; use agent-browser to prepare the page first.
+  Filled/submitted does not mean authenticated: verify a non-secret success state.
+
 Manage secrets with realtimex-pp-cli or Settings > Secrets.
 Requires the running app and its terminal-session environment. No secret cache.
 Runs executables directly, without a shell. Output is UTF-8 with known values
@@ -58,6 +67,11 @@ export async function execute(plan, injected, { stdout = process.stdout, stderr
 
 export async function main(argv, { env = process.env, stdout = process.stdout, stderr = process.stderr, resolver = resolveSecrets } = {}) {
   try {
+    if (['browser-tabs', 'browser-login'].includes(argv[0])) {
+      const result = await runBrowser(parseBrowserArguments(argv), env, { resolver });
+      stdout.write(`${JSON.stringify(result)}\n`);
+      return 0;
+    }
     const plan = parseArguments(argv);
     if (plan.help) { stdout.write(help); return 0; }
     if (plan.version) { stdout.write(`${JSON.parse(readFileSync(new URL('../package.json', import.meta.url))).version}\n`); return 0; }

package/src/client.js

@@ -23,7 +23,7 @@ export async function resolveSecrets(plan, env = process.env, fetchImpl = fetch)
     response = await fetchImpl(url, {
       method: 'POST', redirect: 'error', signal: AbortSignal.timeout(15000),
       headers: { Authorization: `RealtimeX-Terminal ${token}`, 'Content-Type': 'application/json' },
-      body: JSON.stringify({ references: plan.references, executable: path.win32.basename(path.basename(plan.command)) }),
+      body: JSON.stringify({ references: plan.references, executable: path.win32.basename(path.basename(plan.command)), ...(plan.browser ? { browser: plan.browser } : {}) }),
     });
   } catch { throw new UsageError('Could not reach RealTimeX. Check that the app is running; no command was launched.'); }
   let text = '';
@@ -43,6 +43,9 @@ export async function resolveSecrets(plan, env = process.env, fetchImpl = fetch)
   try { body = JSON.parse(text); } catch { throw new UsageError('Invalid RealTimeX response; no command was launched.'); }
   if (!response.ok || body.success !== true) {
     const messages = {
+      SECRET_ORIGIN_DENIED: 'This login is not allowed on the selected website.',
+      SECRET_LOGIN_REQUIRED: 'Select a Login credential for browser login.',
+      SECRET_BROWSER_REQUIRED: 'Use rtxexec browser-login for Login credentials.',
       SECRET_NOT_FOUND: 'A referenced secret does not exist.',
       SECRET_SCOPE_DENIED: 'A referenced secret is not available in this workspace.',
       SECRET_DISABLED: 'A referenced secret is disabled.',