@realtimex/rtxexec 0.2.0 → 0.3.0

package/README.md

@@ -78,3 +78,78 @@ 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.
+
+
+## Structured credential items
+
+RealTimeX stores Login, Card, Identity, SSH key and Secure note items. Management
+stays in Settings or the moderator CLI; rtxexec only uses saved values.
+List metadata to discover `reference` and `fieldNames`. To select a field:
+
+```sh
+rtxexec --env API_TOKEN=secret://service#apiToken -- program
+rtxexec --stdin secret://note#notes -- program
+```
+
+A Login can contain just a password, the built-in API key / Token (`apiToken`),
+or custom fields; a username and website are optional for terminal use. New Login
+defaults to password when present, otherwise `apiToken`; Secure note defaults to
+notes. Existing scalar references keep their value. An explicit move into Password
+or API key / Token preserves both default and `#value` references, including after
+rotation.
+Use explicit field references for Card, Identity and SSH items.
+
+### Fill Card or Identity forms
+
+Prepare a page with agent-browser, identify its visible top-level selectors,
+and use the exact CDP target ID from `browser-tabs`:
+
+```sh
+rtxexec browser-fill secret://card --cdp 9235 --tab TARGET_ID \
+  --field 'number=#card-number' --field 'securityCode=#cvv'
+```
+
+Only mapped fields are requested. The item's permitted origins and workspace
+scope are enforced. Inputs, textareas and selects are supported; iframe forms
+are not. This command never submits. Check non-secret status and perform any
+submission separately within the authorized task. Avoid snapshots, recordings
+and field-value reads while saved data is in the page. `browser-login` remains
+available and now requests only the username/password fields selected.
+
+### SSH and Git
+
+```sh
+rtxexec ssh secret://deploy-key -- ssh user@host
+rtxexec ssh secret://deploy-key -- git fetch origin
+```
+
+Requires OpenSSH (and Git for Git commands). The app unlocks the saved key for
+this execution. rtxexec writes it to a restricted temporary directory, supplies
+the path to SSH or Git, and removes the directory when the child finishes or
+fails. Unix uses directory mode 0700 and file mode 0600; Windows requires icacls
+to restrict the directory before writing. Existing host-key verification stays
+in effect. SIGKILL or a machine crash may prevent cleanup. The CLI keeps no
+persistent vault or secret cache. Output masking is best effort; this is an
+accidental-disclosure safeguard, not a boundary against deliberate local access.
+
+## Linked SSO logins
+
+A Login can keep its normal username/password and link multiple saved Login items
+for SSO. Management uses `ssoCredentialIds` (moderator flag
+`--sso-credential-ids id1,id2`; an empty flag clears links). Names and descriptions
+identify the provider and account; no separate provider instructions are needed.
+
+Use agent-browser to choose the matching sign-in button and reach the provider.
+Then explicitly select the linked Login:
+
+```sh
+rtxexec browser-login secret://rtgit --sso secret://google \
+  --cdp 9235 --tab TARGET_ID \
+  --username-selector '#username' --password-selector '#password'
+```
+
+The server checks both items' enabled state and workspace scope, and the provider's
+allowed website origin. It records usage for both without copying values into the
+site item. Omitting `--sso` uses normal credentials; selection never automatically
+follows further links. Ask when the provider/account is ambiguous, and handle
+already signed-in sessions or MFA through the normal browser workflow.

package/package.json

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

package/src/browser.js

@@ -6,15 +6,24 @@ export function parseBrowserArguments(argv) {
   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'];
+  if (command !== 'browser-tabs') reference = argv[i++];
+  const allowed = command === 'browser-tabs' ? ['cdp'] : command === 'browser-fill' ? ['cdp', 'tab', 'field', 'sso'] : ['cdp', 'tab', 'username-selector', 'password-selector', 'submit-selector', 'sso'];
   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 (!argv[i]?.startsWith('--') || !allowed.includes(key) || (key !== 'field' && options[key] !== undefined) || !argv[i + 1] || argv[i + 1].startsWith('--')) throw new UsageError('Invalid browser option. See rtxexec --help.');
+    if (key === 'field') {
+      const value = argv[i + 1]; const split = value.indexOf('=');
+      const field = value.slice(0, split); const selector = value.slice(split + 1);
+      if (split < 1 || !/^[A-Za-z][A-Za-z0-9_]{0,63}$/.test(field) || !selector || selector.length > 4096 || ['constructor', 'prototype', '__proto__'].includes(field)) throw new UsageError('Use --field fieldName=selector.');
+      options.fields ||= [];
+      if (options.fields.some((entry) => entry.name === field || entry.selector === selector) || options.fields.length >= 32) throw new UsageError('Use up to 32 distinct fields and selectors.');
+      options.fields.push({ name: field, selector });
+    } else 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.');
+  if (command === 'browser-fill' && (!reference?.startsWith('secret://') || reference.includes('#') || !/^[a-zA-Z0-9_-]{1,128}$/.test(options.tab || '') || !options.fields?.length)) throw new UsageError('Provide an item reference, --tab and at least one --field name=selector.');
+  if (options.sso && (!options.sso.startsWith('secret://') || options.sso.includes('#') || options.sso.length > 1024)) throw new UsageError('Use --sso secret://provider with a linked Login item.');
   return { command, reference, ...options };
 }
 
@@ -105,6 +114,38 @@ export function fillLogin(username, password, selectors, expectedOrigin) {
   return { status: submit ? 'submitted' : 'filled' };
 }
 
+
+// Fill-only: submission remains an explicit, separate browser action.
+export function fillFields(values, selectors, expectedOrigin) {
+  const usable = (element) => {
+    if (!element || !element.isConnected || element.disabled || element.matches(':disabled') || element.readOnly || !element.getClientRects().length) return false;
+    if (getComputedStyle(element).visibility !== 'visible') return false;
+    for (let node = element; node; node = node.parentElement) if (Number(getComputedStyle(node).opacity) === 0) return false;
+    return !element.form || new URL(element.form.action || location.href).origin === expectedOrigin;
+  };
+  if (location.origin !== expectedOrigin) return { error: 'origin' };
+  const fields = [];
+  for (const { name, selector } of selectors) {
+    const matches = document.querySelectorAll(selector);
+    const element = matches.length === 1 ? matches[0] : null;
+    if (!usable(element) || !(element instanceof HTMLInputElement || element instanceof HTMLTextAreaElement || element instanceof HTMLSelectElement)) return { error: 'field' };
+    if (element instanceof HTMLInputElement && ['file', 'hidden', 'checkbox', 'radio', 'button', 'submit', 'reset', 'image'].includes(element.type)) return { error: 'field' };
+    if (name === 'password' && (!(element instanceof HTMLInputElement) || element.type !== 'password')) return { error: 'password-field' };
+    if (element instanceof HTMLSelectElement && !Array.from(element.options).some(option => option.value === values[name] && !option.disabled)) return { error: 'option' };
+    if (fields.some(entry => entry.element === element)) return { error: 'duplicate' };
+    fields.push({ element, name, type: element.type });
+  }
+  for (const { element, name, type } of fields) {
+    if (location.origin !== expectedOrigin || !usable(element) || element.type !== type) return { error: 'changed' };
+    const prototype = element instanceof HTMLInputElement ? HTMLInputElement.prototype : element instanceof HTMLSelectElement ? HTMLSelectElement.prototype : HTMLTextAreaElement.prototype;
+    Object.getOwnPropertyDescriptor(prototype, 'value').set.call(element, values[name]);
+    if (element.value !== values[name]) return { error: 'value' };
+    element.dispatchEvent(new Event('input', { bubbles: true }));
+    element.dispatchEvent(new Event('change', { bubbles: true }));
+  }
+  return { status: '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 }; }) };
@@ -120,14 +161,19 @@ export async function runBrowser(plan, env, { targets = browserTargets, connect
       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 requested = plan.command === 'browser-fill' ? plan.fields.map(entry => entry.name) : ['username', 'password'].filter(name => plan[`${name}-selector`]);
+    const values = await resolver({ references: [plan.reference], command: 'rtxexec', browser: { origin, targetId: target.id, fields: requested, ...(plan.sso ? { ssoReference: plan.sso } : {}) } }, 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 fields = credential?.fields || credential;
+    if (requested.some(name => typeof fields?.[name] !== 'string' || !fields[name]) || !Array.isArray(credential?.allowedOrigins) || !credential.allowedOrigins.includes(origin)) throw new UsageError('RealTimeX did not authorize the requested fields for this website.');
+    const args = plan.command === 'browser-fill'
+      ? [Object.fromEntries(requested.map(name => [name, fields[name]])), plan.fields, origin]
+      : [fields.username || '', fields.password || '', { username: plan['username-selector'], password: plan['password-selector'], submit: plan['submit-selector'] }, origin];
     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 })),
+      executionContextId, functionDeclaration: (plan.command === 'browser-fill' ? fillFields : fillLogin).toString(), returnByValue: true,
+      arguments: args.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.');
+    if (result.exceptionDetails || !['filled', 'submitted'].includes(result.result?.value?.status)) throw new UsageError('Form fill 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,4 +1,5 @@
 import { parseBrowserArguments, runBrowser } from "./browser.js";
+import { parseSshArguments, runSsh } from "./ssh.js";
 import { UsageError } from "./error.js";
 import { spawn } from 'node:child_process';
 import { constants } from 'node:os';
@@ -19,10 +20,20 @@ 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>]
+  rtxexec browser-fill secret://name --cdp <port> --tab <CDP-target-id>
+    --field number="#card-number" --field securityCode="#cvv"
+  Add --sso secret://provider to explicitly use a linked SSO Login.
+  browser-fill fills only; use a separate authorized action to submit.
+  Named terminal fields use secret://name#field (for example #apiToken).
   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.
 
+SSH/Git use:
+  rtxexec ssh secret://name -- ssh user@host
+  rtxexec ssh secret://name -- git fetch origin
+  Requires OpenSSH. Creates an owner-only temporary key, removed after exit.
+
 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
@@ -67,11 +78,12 @@ 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])) {
+    if (['browser-tabs', 'browser-login', 'browser-fill'].includes(argv[0])) {
       const result = await runBrowser(parseBrowserArguments(argv), env, { resolver });
       stdout.write(`${JSON.stringify(result)}\n`);
       return 0;
     }
+    if (argv[0] === "ssh") return await runSsh(parseSshArguments(argv), env, (plan, injected) => execute(plan, injected, { stdout, stderr }), { resolver });
     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)), ...(plan.browser ? { browser: plan.browser } : {}) }),
+      body: JSON.stringify({ references: plan.references, executable: path.win32.basename(path.basename(plan.command)), ...(plan.browser ? { browser: plan.browser } : {}), ...(plan.ssh ? { ssh: true } : {}) }),
     });
   } catch { throw new UsageError('Could not reach RealTimeX. Check that the app is running; no command was launched.'); }
   let text = '';
@@ -43,8 +43,12 @@ 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_ORIGIN_DENIED: 'This item is not allowed on the selected website.',
+      SECRET_LOGIN_REQUIRED: 'Select a Login, Card or Identity item for browser fill.',
+      SECRET_FIELD_NOT_FOUND: 'The selected field has no saved value.',
+      SECRET_SSH_REQUIRED: 'Select an SSH key item.',
+      SECRET_SSO_INVALID: 'Select a saved Login linked to this item for SSO.',
+      SECRET_SSO_DENIED: 'The linked SSO Login is disabled or unavailable in this workspace.',
       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.',

package/src/ssh.js

@@ -0,0 +1,45 @@
+import { mkdtemp, writeFile, chmod, rm } from 'node:fs/promises';
+import { tmpdir, userInfo } from 'node:os';
+import path from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { UsageError } from './error.js';
+import { resolveSecrets } from './client.js';
+
+const run = promisify(execFile);
+const quote = value => "'" + value.replace(/'/g, "'\"'\"'") + "'";
+export function parseSshArguments(argv) {
+  if (!argv[1]?.startsWith('secret://') || argv[1].includes('#') || argv[2] !== '--' || !argv[3]) throw new UsageError('Use rtxexec ssh secret://name -- ssh|git [arguments].');
+  const name = path.win32.basename(path.basename(argv[3])).replace(/\.exe$/i, '').toLowerCase();
+  if (!['ssh', 'git'].includes(name)) throw new UsageError('SSH key execution supports ssh and git.');
+  return { references: [argv[1]], command: argv[3], args: argv.slice(4), ssh: true, sshCommand: name };
+}
+
+export async function runSsh(plan, env, execute, { resolver = resolveSecrets, root = tmpdir() } = {}) {
+  const [credential] = await resolver(plan, env);
+  if (typeof credential?.privateKey !== 'string' || !credential.privateKey.includes('-----BEGIN OPENSSH PRIVATE KEY-----') || Buffer.byteLength(credential.privateKey) > 65536) throw new UsageError('RealTimeX did not provide a usable SSH key.');
+  let directory;
+  try {
+    directory = await mkdtemp(path.join(root, 'rtxexec-ssh-'));
+    if (process.platform === 'win32') {
+      // Secure the empty directory before writing material. Fail closed if ACLs
+      // cannot be set (e.g. a non-NTFS temp directory).
+      await run('icacls.exe', [directory, '/inheritance:r', '/grant:r', `${userInfo().username}:(OI)(CI)F`], { windowsHide: true });
+    } else await chmod(directory, 0o700);
+    const keyPath = path.join(directory, 'identity');
+    await writeFile(keyPath, credential.privateKey, { mode: 0o600, flag: 'wx' });
+    const sshArgs = ['-i', keyPath, '-o', 'IdentitiesOnly=yes', '-o', 'IdentityAgent=none'];
+    const childEnv = { ...env };
+    let args = plan.args;
+    if (plan.sshCommand === 'ssh') args = [...sshArgs, ...args];
+    else {
+      // Git consumes this command through its own shell. Only generated paths
+      // and fixed options are included, with POSIX quoting (also used by Git for Windows).
+      childEnv.GIT_SSH_COMMAND = ['ssh', ...sshArgs.map(value => process.platform === 'win32' ? value.replace(/\\/g, '/') : value)].map(quote).join(' ');
+      childEnv.GIT_SSH_VARIANT = 'ssh';
+    }
+    return await execute(plan, { args, env: childEnv, stdin: undefined, values: [credential.privateKey] });
+  } finally {
+    if (directory) await rm(directory, { recursive: true, force: true });
+  }
+}