@relayflows/sdk 2.0.50 → 2.0.52

package/src/step-secrets.ts

@@ -0,0 +1,145 @@
+import type { CliAdapterKind } from './cli-adapter.js';
+
+/** Cloud supplies this name-only manifest alongside delivered envSecrets. */
+export const SECRET_ENV_NAMES = 'RELAY_SECRET_ENV_NAMES';
+/** Cloud's name-only exception for model login it selected from delivered values. */
+export const PLATFORM_AGENT_ENV_NAMES = 'RELAY_PLATFORM_AGENT_ENV_NAMES';
+/** CLI-only hosted signal read capability. Never a run or step secret. */
+export const SIGNAL_READ_TOKEN_ENV = 'RELAYFLOW_V2_SIGNAL_READ_TOKEN';
+const VALID_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const BEDROCK_LOGIN = new Set([
+  'CLAUDE_CODE_USE_BEDROCK', 'AWS_BEARER_TOKEN_BEDROCK',
+  'AWS_ACCESS_KEY_ID', 'AWS_SECRET_ACCESS_KEY', 'AWS_SESSION_TOKEN',
+  'AWS_REGION', 'AWS_DEFAULT_REGION',
+]);
+
+const REPOSITORY_ENV = new Set([
+  'GH_TOKEN', 'GH_CONFIG_DIR', 'GH_PROMPT_DISABLED', 'GITLAB_TOKEN',
+  'RELAYFLOW_V2_GITLAB_API_URL',
+]);
+export function repositoryEnvironmentNames(source: NodeJS.ProcessEnv): string[] {
+  return Object.keys(source).filter(name => REPOSITORY_ENV.has(name) || name.startsWith('GIT_')
+    || name.startsWith('RELAYFLOW_V2_REPOSITORY_'));
+}
+
+const BASE_ENV = [
+  'PATH', 'HOME', 'USER', 'LOGNAME', 'SHELL', 'TERM', 'LANG', 'LANGUAGE',
+  'LC_ALL', 'LC_CTYPE', 'TZ', 'TMPDIR', 'TMP', 'TEMP', 'XDG_RUNTIME_DIR',
+  'XDG_CACHE_HOME', 'XDG_CONFIG_HOME', 'XDG_DATA_HOME', 'HOSTNAME',
+  'NODE_PATH', 'NODE_ENV', 'NODE_EXTRA_CA_CERTS', 'SSL_CERT_FILE',
+  'SSL_CERT_DIR', 'NVM_DIR', 'NVM_BIN', 'NVM_INC',
+  'HTTP_PROXY', 'HTTPS_PROXY', 'ALL_PROXY', 'NO_PROXY',
+  'http_proxy', 'https_proxy', 'all_proxy', 'no_proxy',
+  'NVM_SYMLINK_CURRENT', 'PIPX_HOME', 'PIPX_BIN_DIR', 'PYTHON_PATH',
+  'PYTHON_VERSION', 'PYTHON_SHA256', 'RELAYFILE_MOUNT_PATH',
+  'RELAYFILE_MOUNT_PATHS', 'RELAYFILE_MOUNT_ROOT', 'WORKSPACE_ROOT',
+  'RELAY_BASE_URL',
+  'SystemRoot', 'ComSpec', 'PATHEXT', 'WINDIR',
+] as const;
+
+// Model login is an intrinsic capability of the selected CLI. It is not a
+// run's delivered envSecret; only that CLI gets its own login variables.
+const CLI_LOGIN: Record<CliAdapterKind, readonly string[]> = {
+  claude: [
+    'CLAUDE_CODE_OAUTH_TOKEN', 'CLAUDE_CONFIG_DIR', 'ANTHROPIC_API_KEY', 'ANTHROPIC_AUTH_TOKEN',
+    'ANTHROPIC_BASE_URL', 'CLAUDE_CODE_USE_BEDROCK',
+    'AWS_BEARER_TOKEN_BEDROCK', 'AWS_ACCESS_KEY_ID', 'AWS_SECRET_ACCESS_KEY',
+    'AWS_SESSION_TOKEN', 'AWS_REGION', 'AWS_DEFAULT_REGION',
+  ],
+  codex: ['CODEX_HOME', 'OPENAI_API_KEY', 'OPENAI_BASE_URL', 'OPENAI_API_BASE', 'OPENROUTER_API_KEY'],
+  'relayflows-wrapper-v1': [],
+};
+
+/** A selected CLI can use its own delivered login; generic cloud credentials need a grant. */
+export function isCliLoginName(kind: string, name: string, providerNames?: readonly string[]): boolean {
+  if (BEDROCK_LOGIN.has(name) || name.startsWith('AWS_')
+    || name === 'GOOGLE_APPLICATION_CREDENTIALS' || name === 'GOOGLE_API_KEY') return false;
+  const names = providerNames ?? (Object.hasOwn(CLI_LOGIN, kind) ? CLI_LOGIN[kind as CliAdapterKind] : []);
+  return names.includes(name);
+}
+
+export function deliveredNames(source: NodeJS.ProcessEnv): ReadonlySet<string> | undefined {
+  const raw = source[SECRET_ENV_NAMES];
+  if (raw === undefined) return undefined; // self-hosted runs may grant present env names
+  let parsed: unknown;
+  try { parsed = JSON.parse(raw); } catch { throw new Error(`${SECRET_ENV_NAMES} must be a JSON array of names`); }
+  if (!Array.isArray(parsed) || !parsed.every(name => typeof name === 'string' && VALID_NAME.test(name))) {
+    throw new Error(`${SECRET_ENV_NAMES} must be a JSON array of valid names`);
+  }
+  if (new Set(parsed).size !== parsed.length || parsed.includes(SECRET_ENV_NAMES)
+    || parsed.includes(PLATFORM_AGENT_ENV_NAMES)
+    || parsed.includes(SIGNAL_READ_TOKEN_ENV)) {
+    throw new Error(`${SECRET_ENV_NAMES} contains a duplicate or reserved name`);
+  }
+  return new Set(parsed);
+}
+
+/** Only Cloud-selected Claude Bedrock login may override the delivered filter. */
+export function platformAgentNames(source: NodeJS.ProcessEnv, kind: string): ReadonlySet<string> {
+  const raw = source[PLATFORM_AGENT_ENV_NAMES];
+  if (raw === undefined) return new Set();
+  let parsed: unknown;
+  try { parsed = JSON.parse(raw); } catch { throw new Error(`${PLATFORM_AGENT_ENV_NAMES} must be a JSON array of names`); }
+  if (!Array.isArray(parsed) || !parsed.every(name => typeof name === 'string' && BEDROCK_LOGIN.has(name)
+    && typeof source[name] === 'string') || new Set(parsed).size !== parsed.length) {
+    throw new Error(`${PLATFORM_AGENT_ENV_NAMES} contains an invalid or unavailable model login name`);
+  }
+  return kind === 'claude' ? new Set(parsed) : new Set();
+}
+
+/** Refuse a misspelled, unavailable or platform-owned name before a child runs. */
+export function validateStepSecrets(declaration: unknown, source: NodeJS.ProcessEnv): string[] {
+  const known = deliveredNames(source);
+  if (declaration === undefined) return [];
+  if (!Array.isArray(declaration) || !declaration.every(name => typeof name === 'string' && VALID_NAME.test(name))) {
+    throw new Error('step secrets must be an array of environment variable names');
+  }
+  const names = declaration as string[];
+  if (new Set(names).size !== names.length) throw new Error('step secrets contain duplicate names');
+  for (const name of names) {
+    if (name === SECRET_ENV_NAMES || name === PLATFORM_AGENT_ENV_NAMES || name === SIGNAL_READ_TOKEN_ENV
+      || !Object.hasOwn(source, name) || typeof source[name] !== 'string'
+      || (known !== undefined && !known.has(name))) {
+      throw new Error(`step secret ${JSON.stringify(name)} is not available to this run`);
+    }
+  }
+  return [...names];
+}
+
+/** One provider CLI starts from an allowlist, then receives only its grants. */
+export function agentStepEnvironment(
+  source: NodeJS.ProcessEnv,
+  kind: CliAdapterKind,
+  declaration?: unknown,
+): NodeJS.ProcessEnv {
+  const known = deliveredNames(source);
+  const platform = platformAgentNames(source, kind);
+  const grants = validateStepSecrets(declaration, source);
+  const env: NodeJS.ProcessEnv = {};
+  for (const name of [...BASE_ENV, ...CLI_LOGIN[kind], ...repositoryEnvironmentNames(source)]) {
+    if (known?.has(name) && !grants.includes(name) && !platform.has(name)
+      && !isCliLoginName(kind, name)) continue;
+    if (source[name] !== undefined) env[name] = source[name];
+  }
+  for (const name of grants) env[name] = source[name];
+  return env;
+}
+
+/** Provider readiness probes run before worker attach, but obey the step's grants. */
+export function agentProbeEnvironment(
+  source: NodeJS.ProcessEnv,
+  kind: CliAdapterKind,
+  declaration?: unknown,
+): NodeJS.ProcessEnv {
+  const env = { ...source };
+  const allowed = new Set(validateStepSecrets(declaration, source));
+  const platform = platformAgentNames(source, kind);
+  for (const name of deliveredNames(source) ?? []) {
+    if (!allowed.has(name) && !platform.has(name) && !isCliLoginName(kind, name)) delete env[name];
+  }
+  delete env[SECRET_ENV_NAMES];
+  delete env[PLATFORM_AGENT_ENV_NAMES];
+  delete env[SIGNAL_READ_TOKEN_ENV];
+  delete env.RELAY_AGENT_TOKEN;
+  return env;
+}

package/src/validate.ts

@@ -388,6 +388,14 @@ class Validator {
     const type = st['type'] as StepType;
     this.checkKeys(st, [...STEP_COMMON_FIELDS, ...STEP_FIELDS_BY_TYPE[type]], at);
 
+    if (st['secrets'] !== undefined) {
+      const names = st['secrets'];
+      if (!Array.isArray(names) || !names.every(name => typeof name === 'string' && /^[A-Za-z_][A-Za-z0-9_]*$/.test(name))
+        || new Set(names).size !== names.length || names.includes('RELAY_SECRET_ENV_NAMES')) {
+        this.fail(`${at}.secrets: expected distinct environment variable names`);
+      }
+    }
+
     if (st['requirements'] !== undefined) this.validateRequirements(st['requirements'], `${at}.requirements`);
     if (st['memory'] !== undefined) this.validateMemory(st['memory'], `${at}.memory`);
 
@@ -491,6 +499,9 @@ class Validator {
   }
 
   private validateAgent(st: AgentStepSpec, at: string): void {
+    if (st.transport === 'relay' && st.secrets?.length) {
+      this.fail(`${at}.secrets: relay transport cannot deliver per-step secrets`);
+    }
     if (st.timeoutMs !== undefined) {
       if (!isPosInt(st.timeoutMs) || st.timeoutMs > 60 * 60_000) {
         this.fail(`${at}.timeoutMs: expected a positive integer at most 3600000 (60 minutes)`);

package/src/worker-cli.ts

@@ -31,6 +31,7 @@ import {
 } from './wrapper-session.js';
 import { wrapperEnvironment } from './wrapper-runtime.js';
 import { applyStepEnvironment } from './step-env.js';
+import { PLATFORM_AGENT_ENV_NAMES, SIGNAL_READ_TOKEN_ENV, agentStepEnvironment } from './step-secrets.js';
 import { TAIL_CLOSE_TIMEOUT_MS, openTranscriptTail, type TranscriptTailWriter } from './transcript-tail.js';
 import {
   isRetryableSpawnError,
@@ -139,12 +140,33 @@ export async function runAgentCli(
   stepTimeoutMs?: number,
   /** A recorded CLI session to continue (`f.agent` `resume`); agent mode only. */
   resume?: string,
+  /** Names of run secrets this step was granted by its journaled spec. */
+  secrets?: string[],
+  /** A featureless daemon retains its legacy child environment for plain runs. */
+  scopeSecrets = true,
 ): Promise<WorkerCliResult> {
   signal?.throwIfAborted();
   if (signal !== undefined && process.platform === 'win32') {
     throw new Error('Lease-bound agent execution requires macOS or Linux process-group cancellation; Windows is unsupported.');
   }
   const kind = cliAdapterKind(cliIdentity ?? cli);
+  if (!scopeSecrets && secrets?.length) {
+    return { exit_code: null, stdout_tail: '',
+      stderr_tail: 'per-step secret grants require a daemon with step_secret_scoping support' };
+  }
+  let childEnvironment: NodeJS.ProcessEnv;
+  try {
+    childEnvironment = scopeSecrets
+      ? agentStepEnvironment(processEnvironment, kind, secrets)
+      : { ...processEnvironment };
+    // The old-daemon compatibility path retains other legacy variables, but
+    // this CLI-only signal capability must never enter an agent subprocess.
+    delete childEnvironment[SIGNAL_READ_TOKEN_ENV];
+    delete childEnvironment[PLATFORM_AGENT_ENV_NAMES];
+  } catch (error) {
+    return { exit_code: null, stdout_tail: '',
+      stderr_tail: error instanceof Error ? error.message : 'step secret grant is invalid' };
+  }
   const effectiveModel = resolveCliModel(cliIdentity ?? cli, model);
   const argv0 = cliInvocationArgv0(cli, cliIdentity);
 
@@ -206,7 +228,8 @@ export async function runAgentCli(
   if (kind === 'relayflows-wrapper-v1') {
     // The closed allowlist admits no ambient RELAYFLOW_* value; the four
     // discovery names are set from this dispatch, exactly as for a direct spawn.
-    const wrapperEnv = wrapperEnvironment(processEnvironment);
+    const wrapperEnv = wrapperEnvironment(childEnvironment);
+    for (const name of secrets ?? []) wrapperEnv[name] = childEnvironment[name];
     applyStepEnvironment(wrapperEnv, sidechannel);
     const session = await runWrapperSession(
       cli,
@@ -225,7 +248,7 @@ export async function runAgentCli(
     return requirePricedUsage(session.transport?.cause === 'timeout' ? { ...decoded, stdout_tail: '' } : decoded, effectiveModel);
   }
 
-  const env: NodeJS.ProcessEnv = { ...processEnvironment };
+  const env: NodeJS.ProcessEnv = { ...childEnvironment };
   delete env[WAKE_CONTEXT_ENV];
   delete env[MODEL_ENV];
   // Where this attempt's journal is, so the agent can run `flows status` on
@@ -256,9 +279,13 @@ export async function runAgentCli(
   const args = [...invocation.args];
   args.splice(args.length - promptOperand('').length, 0, ...(kind === 'claude' ? ['--output-format', 'stream-json', '--verbose'] : ['--json']));
   const completion = kind === 'claude' ? claudeResultOutcome : undefined;
+  // Retain the source values for output redaction even though the child
+  // receives only its filtered environment. A provider can echo a value from
+  // its prompt or fixture that was not granted as an environment variable.
+  const redactionEnvironment = { ...processEnvironment, ...env };
   return requirePricedUsage(decodeProviderResult(await spawnInvocation(
-    cli, { ...invocation, args }, env, signal, sidechannel, cwd, completion, argv0, kind,
-  ), kind, env), effectiveModel);
+    cli, { ...invocation, args }, env, signal, sidechannel, cwd, completion, argv0, kind, redactionEnvironment,
+  ), kind, redactionEnvironment), effectiveModel);
   }
 }
 
@@ -399,6 +426,7 @@ async function spawnInvocation(
   completion?: (line: string) => { failed: boolean } | undefined,
   argv0?: string,
   kind?: CliAdapterKind,
+  redactionEnvironment: NodeJS.ProcessEnv = env,
 ): Promise<WorkerCliResult> {
   const pendingInput: Buffer[] = [];
   let acceptingDrive = true;
@@ -436,7 +464,7 @@ async function spawnInvocation(
   };
   try {
     writer = sidechannel?.attempt === undefined ? undefined
-      : await openTranscriptWriter(transcriptPath(sidechannel, sidechannel.attempt), env);
+      : await openTranscriptWriter(transcriptPath(sidechannel, sidechannel.attempt), redactionEnvironment);
     channel = sidechannel === undefined ? undefined : await openSidechannel({
       ...sidechannel,
       onDrive() { driven = true; sidechannel.onDrive(); },
@@ -597,7 +625,7 @@ async function spawnInvocation(
       const transport = transportEvidence({
         phase: 'abort', cause: 'lease_lost', exitCode: null, signal: null,
         stderr: 'Agent execution aborted: lease ownership lost.', retryable: false,
-      }, env);
+      }, redactionEnvironment);
       finishAfterStop(
         { exit_code: null, stdout_tail: '', stderr_tail: 'Agent execution aborted: lease ownership lost.', transport },
         'kill',
@@ -635,11 +663,11 @@ async function spawnInvocation(
           phase: 'result_exit_grace', cause: 'result_exit_timeout', exitCode, signal: null,
           stderr: stderrText,
           retryable: false,
-        }, env);
+        }, redactionEnvironment);
         finishAfterStop({
           exit_code: exitCode,
           stdout_tail: Buffer.concat(stdout).toString('utf8'),
-          stderr_tail: redactText(stderrText, env),
+          stderr_tail: redactText(stderrText, redactionEnvironment),
           transport,
         }, 'terminate');
       }, RESULT_EXIT_GRACE_MS);
@@ -671,11 +699,11 @@ async function spawnInvocation(
       const transport = transportEvidence({
         phase: 'spawn', cause: child.pid === undefined ? 'spawn_error' : 'process_error',
         exitCode: null, signal: null, stderr: error.message, errorCode: code, retryable,
-      }, env);
+      }, redactionEnvironment);
       finishOnChildExit({
         exit_code: null,
         stdout_tail: Buffer.concat(stdout).toString('utf8'),
-        stderr_tail: redactText(error.message, env),
+        stderr_tail: redactText(error.message, redactionEnvironment),
         transport,
       });
     });
@@ -692,11 +720,11 @@ async function spawnInvocation(
       const retryable = codexStdinLifecycle || signalName !== null || code === null;
       const transport = transportEvidence({
         phase: 'close', cause, exitCode: code, signal: signalName, stderr: stderrText, retryable,
-      }, env);
+      }, redactionEnvironment);
       finishOnChildExit({
         exit_code: code,
         stdout_tail: Buffer.concat(stdout).toString('utf8'),
-        stderr_tail: redactText(stderrText, env),
+        stderr_tail: redactText(stderrText, redactionEnvironment),
         transport,
       });
     });
@@ -710,7 +738,7 @@ async function spawnInvocation(
           phase: 'timeout', cause: 'timeout', exitCode: null, signal: null,
           stderr: `${Buffer.concat(stderr).toString('utf8')}\n${timeoutMessage}`,
           retryable: false,
-        }, env);
+        }, redactionEnvironment);
         finishAfterStop({
           exit_code: null,
           stdout_tail: Buffer.concat(stdout).toString('utf8'),

package/src/worker.ts

@@ -39,7 +39,7 @@ export interface AgentWorkerOptions {
    * the root a dispatch is measured against is a value, not an assumption.
    */
   runRoot?: string;
-  /** Environment inherited by provider CLIs, including agent-only secrets. */
+  /** Source environment; each provider CLI receives only its allowlist and step grants. */
   environment?: NodeJS.ProcessEnv;
 }
 
@@ -156,7 +156,8 @@ export class AgentWorker extends EventEmitter {
             spec.transport === 'relay' ? 'relay' : 'direct',
             { runId: dispatch.run_id, stepId: dispatch.step_id, idempotencyKey: dispatch.idempotency_key,
               dataDir: this.options.dataDir, resultSchema: spec.verification?.json_schema },
-            this.options.environment, spec.cli_identity, spec.timeout_ms, spec.resume)
+            this.options.environment, spec.cli_identity, spec.timeout_ms, spec.resume, spec.secrets,
+            this.client.supportsFeature?.('step_secret_scoping') ?? true)
           : Promise.resolve({ exit_code: null, stdout_tail: '', stderr_tail: 'agent step has no declared CLI' }));
     const { result, usage } = workerSpend(completed, effectiveModel);
     const cost = reportedCost(completed, effectiveModel);