@realtimex/rtxexec 0.1.0

package/README.md

@@ -0,0 +1,43 @@
+# rtxexec
+
+Run local commands with secrets stored in the RealTimeX app. Node.js 20+;
+macOS, Linux, and Windows. Install with `npm install -g @realtimex/rtxexec`.
+
+Create/manage secrets in Settings > Secrets or with the moderator
+`realtimex-pp-cli`. This package deliberately has no vault-management commands.
+
+```sh
+rtxexec --env GH_TOKEN=secret://github-token -- gh issue list
+rtxexec --stdin secret://registry-token -- docker login registry.example.com --username alice --password-stdin
+rtxexec --secret token=secret://github-token -- curl -H 'Authorization: Bearer {{token}}' https://api.github.com/user
+```
+
+Run inside a RealTimeX terminal session. The app supplies
+`REALTIMEX_TERMINAL_SESSION_TOKEN` and `REALTIMEX_BASE_URL` (ending in `/cli`).
+`SERVER_URL` is a fallback. Connections are local only and never follow redirects.
+Workspace authorization comes from the server's authenticated session, not a
+caller-provided `RTX_WORKSPACE_SLUG`. Missing/disabled/out-of-scope values fail
+before the child starts. Secrets are retrieved anew; there is no local cache.
+
+The optional `run` subcommand is also accepted. Bindings precede `--`; everything after it is the executable and literal argument
+array. Placeholder expansion happens once, inside arguments, with no shell eval.
+Quote placeholders for your shell (single quotes in Bash, zsh, and PowerShell).
+Percent-encode legacy names containing spaces in secret references. Environment
+bindings affect only the child. `--stdin` sends the exact value without adding a
+newline and closes stdin; without it, stdin is inherited.
+
+The child receives the real value. Known plaintext, URI-encoded, JSON-escaped,
+and base64 values are masked in UTF-8 stdout/stderr, including split chunks.
+This reduces accidental disclosure; it does not prevent arbitrary child programs
+from saving or transmitting secrets. Argument injection can expose values in
+process inspection. Do not ask agents to retrieve raw secrets or bypass masking.
+
+Exit codes are propagated. Signal exits use 128 + signal number. POSIX signals
+are forwarded to the child process group; Windows uses Node's child termination
+behavior and cannot promise POSIX process-group semantics. Output is piped, not a
+PTY: full-screen tools and programs requiring an interactive TTY are unsupported.
+Use native executables on Windows; invoke JavaScript CLIs as `node path/to/cli.js`
+when the installed launcher is a .cmd/.bat file. Shell pipelines must be composed
+explicitly; the wrapper does not interpret shell syntax.
+
+`npm test` runs isolated fixtures. `npm pack --dry-run` validates package contents.

package/bin/rtxexec.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { main } from '../src/cli.js';
+process.exitCode = await main(process.argv.slice(2));

package/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "@realtimex/rtxexec",
+  "version": "0.1.0",
+  "description": "Run commands with secrets from the RealTimeX app vault",
+  "type": "module",
+  "bin": { "rtxexec": "bin/rtxexec.js" },
+  "files": ["bin", "src", "README.md"],
+  "engines": { "node": ">=20" },
+  "scripts": { "test": "node --test" },
+  "license": "MIT",
+  "publishConfig": { "access": "public" },
+  "repository": { "type": "git", "url": "git+https://github.com/therealtimex/realtimex-sdk.git", "directory": "rtxexec" }
+}

package/src/arguments.js

@@ -0,0 +1,46 @@
+import { UsageError } from "./error.js";
+const aliasPattern = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const referencePattern = /^secret:\/\/.+$/;
+
+export function parseArguments(argv) {
+  if (argv.length === 1 && ['--help', '-h'].includes(argv[0])) return { help: true };
+  if (argv.length === 1 && argv[0] === '--version') return { version: true };
+  const start = argv[0] === 'run' ? 1 : 0;
+  if (!['--env', '--secret', '--stdin'].includes(argv[start])) throw new UsageError('Use rtxexec [bindings] -- command [arguments]. Secret management belongs to realtimex-pp-cli.');
+  const separator = argv.indexOf('--');
+  if (separator < 0 || !argv[separator + 1]) throw new UsageError('Specify -- followed by an executable.');
+  const env = new Map(); const aliases = new Map(); let stdin;
+  for (let i = start; i < separator; i += 2) {
+    const option = argv[i]; const binding = argv[i + 1];
+    if (!['--env', '--secret', '--stdin'].includes(option) || i + 1 >= separator) throw new UsageError('Expected --env NAME=secret://name, --secret alias=secret://name, or --stdin secret://name.');
+    if (option === '--stdin') {
+      if (stdin || !referencePattern.test(binding)) throw new UsageError('Supply one secret reference for --stdin.');
+      stdin = binding; continue;
+    }
+    const equals = binding.indexOf('=');
+    const name = binding.slice(0, equals); const reference = binding.slice(equals + 1);
+    const target = option === '--env' ? env : aliases;
+    if (equals < 1 || !aliasPattern.test(name) || !referencePattern.test(reference) || target.has(name)) throw new UsageError('Invalid or duplicate secret binding.');
+    target.set(name, reference);
+  }
+  const references = [...new Set([...env.values(), ...aliases.values(), ...(stdin ? [stdin] : [])])];
+  if (!references.length || references.length > 32 || references.some((ref) => ref.length > 1024)) throw new UsageError('Bind between 1 and 32 secrets.');
+  const command = argv[separator + 1]; const args = argv.slice(separator + 2);
+  if (command.includes('{{') || command.includes('\0')) throw new UsageError('The executable cannot contain a secret placeholder.');
+  for (const arg of args) for (const match of arg.matchAll(/\{\{([A-Za-z_][A-Za-z0-9_]*)\}\}/g)) {
+    if (!aliases.has(match[1])) throw new UsageError('An argument uses an undeclared secret placeholder.');
+  }
+  return { command, args, env, aliases, stdin, references };
+}
+
+export function inject(plan, secrets, environment) {
+  const values = new Map(secrets.map(({ reference, value }) => [reference, value]));
+  for (const reference of plan.references) {
+    const value = values.get(reference);
+    if (typeof value !== 'string' || !value || value.includes('\0') || Buffer.byteLength(value) > 65536) throw new UsageError('The app returned an invalid or missing secret value.');
+  }
+  const env = { ...environment };
+  for (const [name, reference] of plan.env) env[name] = values.get(reference);
+  const args = plan.args.map((arg) => arg.replace(/\{\{([A-Za-z_][A-Za-z0-9_]*)\}\}/g, (_, name) => values.get(plan.aliases.get(name))));
+  return { args, env, stdin: plan.stdin ? values.get(plan.stdin) : undefined, values: [...values.values()] };
+}

package/src/cli.js

@@ -0,0 +1,73 @@
+import { UsageError } from "./error.js";
+import { spawn } from 'node:child_process';
+import { constants } from 'node:os';
+import { readFileSync } from 'node:fs';
+import { finished } from 'node:stream/promises';
+import { parseArguments, inject } from './arguments.js';
+import { resolveSecrets } from './client.js';
+import { SecretMask } from './mask.js';
+
+const help = `rtxexec — run commands using RealTimeX secrets
+
+Usage: rtxexec [bindings] -- executable [arguments]
+  --env NAME=secret://name       Inject a child environment variable
+  --secret alias=secret://name   Substitute {{alias}} inside argument values
+  --stdin secret://name          Write the exact value to child stdin, then close it
+
+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
+masked; transformed output, files, network traffic, and child arguments may
+expose secrets. Full-screen/TTY applications are not supported. On Windows,
+use native executables or node with a script path, rather than .cmd/.bat files.
+`;
+
+export async function execute(plan, injected, { stdout = process.stdout, stderr = process.stderr, signalSource = process, spawnImpl = spawn } = {}) {
+  const child = spawnImpl(plan.command, injected.args, {
+    env: injected.env, shell: false, windowsHide: true,
+    detached: process.platform !== 'win32',
+    stdio: [injected.stdin === undefined ? 'inherit' : 'pipe', 'pipe', 'pipe'],
+  });
+  const outMask = new SecretMask(injected.values); const errMask = new SecretMask(injected.values);
+  child.stdout.pipe(outMask).pipe(stdout, { end: false });
+  child.stderr.pipe(errMask).pipe(stderr, { end: false });
+  const streams = Promise.all([finished(outMask), finished(errMask)]);
+  const forwards = new Map(['SIGINT', 'SIGTERM', 'SIGHUP'].map((signal) => [signal, () => {
+    try {
+      if (process.platform !== 'win32' && child.pid) process.kill(-child.pid, signal);
+      else child.kill(signal);
+    } catch { /* Child already exited. */ }
+  }]));
+  for (const [signal, handler] of forwards) signalSource.on(signal, handler);
+  try {
+    if (injected.stdin !== undefined) {
+      child.stdin.on('error', () => {}); // Programs may close stdin before consuming it.
+      child.stdin.end(injected.stdin);
+    }
+    const outcome = await new Promise((resolve) => {
+      child.once('error', (error) => resolve({ failed: error.code === 'ENOENT' ? 127 : 126 }));
+      child.once('close', (code, signal) => resolve({ code, signal }));
+    });
+    await streams;
+    if (outcome.failed) { stderr.write('rtxexec: could not launch executable. Check its installation and permissions.\n'); return outcome.failed; }
+    return outcome.signal ? 128 + (constants.signals[outcome.signal] || 1) : outcome.code ?? 1;
+  } finally {
+    for (const [signal, handler] of forwards) signalSource.removeListener(signal, handler);
+  }
+}
+
+export async function main(argv, { env = process.env, stdout = process.stdout, stderr = process.stderr, resolver = resolveSecrets } = {}) {
+  try {
+    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; }
+    const secrets = await resolver(plan, env);
+    const injected = inject(plan, secrets, env);
+    return await execute(plan, injected, { stdout, stderr });
+  } catch (error) {
+    // All expected messages are authored locally; never print fetch/spawn errors,
+    // which can contain authorization headers or expanded child arguments.
+    stderr.write(`rtxexec: ${error instanceof UsageError ? error.message : "Execution failed; no diagnostic containing secret values was printed."}\n`);
+    return 1;
+  }
+}

package/src/client.js

@@ -0,0 +1,55 @@
+import { UsageError } from "./error.js";
+import path from 'node:path';
+
+export function resolveEndpoint(env) {
+  const base = env.REALTIMEX_BASE_URL || (env.SERVER_URL ? `${env.SERVER_URL.replace(/\/$/, '')}/cli` : '');
+  let url;
+  try { url = new URL(base); } catch { throw new UsageError('RealTimeX connection is missing. Run this command in a RealTimeX terminal session.'); }
+  if (!['http:', 'https:'].includes(url.protocol) || !['localhost', '127.0.0.1', '[::1]'].includes(url.hostname) || url.username || url.password || url.search || url.hash) {
+    throw new UsageError('rtxexec requires a local RealTimeX server URL.');
+  }
+  const prefix = url.pathname.replace(/\/$/, '');
+  if (!prefix.endsWith('/cli')) throw new UsageError('REALTIMEX_BASE_URL must end with /cli.');
+  url.pathname = `${prefix}/secrets/resolve`;
+  return url;
+}
+
+export async function resolveSecrets(plan, env = process.env, fetchImpl = fetch) {
+  const url = resolveEndpoint(env);
+  const token = env.REALTIMEX_TERMINAL_SESSION_TOKEN;
+  if (!token) throw new UsageError('No terminal session token. Run rtxexec inside RealTimeX.');
+  let response;
+  try {
+    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)) }),
+    });
+  } catch { throw new UsageError('Could not reach RealTimeX. Check that the app is running; no command was launched.'); }
+  let text = '';
+  try {
+    const reader = response.body.getReader(); const decoder = new TextDecoder(); let bytes = 0;
+    try {
+      for (;;) {
+        const { done, value } = await reader.read(); if (done) break;
+        bytes += value.length;
+        if (bytes > 4 * 1024 * 1024) { await reader.cancel(); throw new UsageError(); }
+        text += decoder.decode(value, { stream: true });
+      }
+      text += decoder.decode();
+    } finally { reader.releaseLock(); }
+  } catch { throw new UsageError('Could not read the credential response; no command was launched.'); }
+  let body;
+  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_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.',
+      SECRET_UNDECRYPTABLE: 'A secret cannot be decrypted. Replace its value in Settings > Secrets.',
+    };
+    throw new UsageError(messages[body.code] || `RealTimeX denied secret resolution (HTTP ${response.status}). Check session authentication and secret settings.`);
+  }
+  if (!Array.isArray(body.secrets) || body.secrets.length !== plan.references.length || body.secrets.some((item) => !item || !plan.references.includes(item.reference))) throw new UsageError('Invalid RealTimeX credential response.');
+  return body.secrets;
+}

package/src/error.js

@@ -0,0 +1 @@
+export class UsageError extends Error {}

package/src/mask.js

@@ -0,0 +1,32 @@
+import { Transform } from 'node:stream';
+import { StringDecoder } from 'node:string_decoder';
+
+export function secretVariants(values) {
+  return [...new Set(values.filter(Boolean).flatMap((value) => [value, encodeURIComponent(value), Buffer.from(value).toString('base64'), JSON.stringify(value).slice(1, -1)]))].sort((a, b) => b.length - a.length);
+}
+
+// Hold only a suffix that can still become a secret. A fixed tail is unnecessary
+// and would delay ordinary short output and interactive-looking progress lines.
+export class SecretMask extends Transform {
+  constructor(values) {
+    super(); this.secrets = secretVariants(values); this.pending = ''; this.decoder = new StringDecoder('utf8');
+  }
+  drain(final) {
+    let at = 0; let output = '';
+    while (at < this.pending.length) {
+      const tail = this.pending.slice(at);
+      if (!final && this.secrets.some((secret) => secret.length > tail.length && secret.startsWith(tail))) break;
+      const match = this.secrets.find((secret) => tail.startsWith(secret));
+      if (match) { output += '[redacted]'; at += match.length; }
+      else { output += this.pending[at]; at++; }
+    }
+    this.pending = this.pending.slice(at);
+    if (output) this.push(output);
+  }
+  _transform(chunk, encoding, callback) {
+    this.pending += this.decoder.write(chunk); this.drain(false); callback();
+  }
+  _flush(callback) {
+    this.pending += this.decoder.end(); this.drain(true); callback();
+  }
+}