@starci/hfs 4.7.9 → 4.7.11

package/runtime/packages/cli/src/validate-args.mjs

@@ -120,6 +120,16 @@ const defaultArgs = (locals, values) => {
   return args;
 };
 
+/** Select the catalogued action policy; a missing policy refuses before runtime or provider dispatch. */
+const operationPolicyOf = (verb, positionals) => {
+  if (verb.operationPolicy === undefined) return null;
+  const policy = verb.operationPolicy?.[positionals[0]];
+  if (!policy || typeof policy.action !== 'string' || !Array.isArray(policy.credentials)) {
+    throw new Error('the selected action has no executable operation policy');
+  }
+  return policy;
+};
+
 /**
  * Validate the arguments after a catalog group and verb.
  *
@@ -166,7 +176,8 @@ export function validateArgs(argv, verb, globalFlags = []) {
     requiredCheck(locals, values);
     checkPositionals(verb, positionals, passthrough);
     checkGlobals(verb, global);
-    return { ok: true, values, args: defaultArgs(locals, values), global, localArgs, positionals };
+    const operationPolicy = operationPolicyOf(verb, positionals);
+    return { ok: true, values, args: defaultArgs(locals, values), global, localArgs, positionals, operationPolicy };
   } catch (error) {
     return { ok: false, code: 2, error: String(error?.message ?? error) };
   }

package/stack/cli.mjs

@@ -7,6 +7,7 @@ import { stackContext } from './context.mjs';
 import { loadDeployConfig } from './config.mjs';
 import { withDockerTransport } from './docker-transport.mjs';
 import { StackError, EXIT, refusal } from './errors.mjs';
+import { parseTargetBinding, bindStackTarget, nativeToolEnvironment } from './target-binding.mjs';
 
 /** The actions that drive the docker CLI of the operator machine (pointed at the manager by docker-transport.mjs when the key is sealed). */
 const DOCKER_ACTIONS = new Set(['deploy', 'accept', 'converge', 'verify', 'rollback', 'prune']);
@@ -14,7 +15,7 @@ const DOCKER_ACTIONS = new Set(['deploy', 'accept', 'converge', 'verify', 'rollb
 export const ACTIONS = Object.freeze(['prepare', 'doctor', 'connect', 'disconnect', 'build-args', 'render', 'deploy', 'converge', 'verify', 'rollback', 'prune', 'backup', 'jobs', 'task', 'ingress', 'retire', 'build', 'accept']);
 
 const BOOLEAN = new Set(['--execute', '--json', '--swarm-state', '--init-swarm', '--owner-approved', '--fix-live-restore', '--skip-public', '--skip-internal', '--allow-unpinned', '--push']);
-const VALUE = new Set(['--env', '--image', '--source-sha', '--previous', '--out', '--release', '--since', '--timeout', '--retry', '--keep', '--app', '--ssh-cmd', '--extra-compose', '--project']);
+const VALUE = new Set(['--env', '--image', '--source-sha', '--previous', '--out', '--release', '--since', '--timeout', '--retry', '--keep', '--app', '--ssh-cmd', '--extra-compose', '--project', '--target-binding']);
 const REPEAT = new Set(['--image', '--keep', '--extra-compose', '--project']);
 
 /** Splits argv into { flags, positional }; an unknown flag or a flag without its value is a refusal. */
@@ -107,6 +108,12 @@ function print(ctx, action, flags, result) {
   else for (const line of result.lines ?? []) ctx.stdout(`${line}\n`);
 }
 
+function nativeToolContext(ctx, binding) {
+  if (!binding) return ctx;
+  return Object.create(ctx, { spawn: { value: (command, args, options = {}) => ctx.spawn(command, args,
+    { ...options, env: nativeToolEnvironment(options.env ?? ctx.env) }) } });
+}
+
 /** Runs one action; returns the exit code. `io.importer` lets a spec load fake action modules. */
 export async function stackMain(argv, io = {}) {
   const ctx = stackContext(io);
@@ -114,12 +121,16 @@ export async function stackMain(argv, io = {}) {
     const { flags, positional } = parseFlags(argv.slice(1));
     const action = argv[0];
     if (!ACTIONS.includes(action)) throw refusal('STACK_USAGE', `starci app stack takes ${[...ACTIONS, 'up', 'down', 'status'].join(', ')}`);
-    const config = loadDeployConfig({ repoRoot: ctx.cwd, env: flags.env ?? 'production' });
+    const binding = parseTargetBinding(flags['target-binding'], 'docker-swarm');
+    if (binding && (!['deploy', 'verify'].includes(action) || flags['ssh-cmd'] || flags['skip-public'] || flags['skip-internal']))
+      throw refusal('STACK_USAGE', 'the bound native consumer supports only complete deploy or verify');
+    const config = bindStackTarget(ctx, loadDeployConfig({ repoRoot: ctx.cwd, env: flags.env ?? 'production' }), binding);
     const options = OPTIONS[action]({ flags, positional, cwd: ctx.cwd });
     const handler = await handlerOf(action, io.importer ?? ((file) => import(file)));
     const sshCmd = flags['ssh-cmd'] ?? null;
     const call = (context) => handler(context, config, { ...options, sshCmd });
-    const result = DOCKER_ACTIONS.has(action) ? await withDockerTransport(ctx, config, { sshCmd }, call) : await call(ctx);
+    const toolContext = nativeToolContext(ctx, binding);
+    const result = DOCKER_ACTIONS.has(action) ? await withDockerTransport(toolContext, config, { sshCmd }, call) : await call(toolContext);
     print(ctx, action, flags, result);
     return result.ok ? EXIT.ok : EXIT.failed;
   } catch (error) {

package/stack/docker-transport.mjs

@@ -17,6 +17,7 @@ const controlLines = (controlPath) => controlSettings(configPath(controlPath)).m
 
 /** True when the operator's docker CLI has to be pointed at the manager by this module. */
 function needed(ctx, config, sshCmd) {
+  if (config.nativeTarget) return true;
   if (sshCmd || ctx.env.DOCKER_HOST || ctx.env.GITHUB_ACTIONS === 'true' || ctx.env.STARCI_STACK_SEALED_SSH === '0') return false;
   const { sealed } = config.remote;
   if (!sealed) return false;
@@ -27,6 +28,7 @@ function sshConfig(session, controlPath, windows) {
   const at = session.account.lastIndexOf('@');
   return [
     `Host ${ALIAS}`, `  HostName ${session.account.slice(at + 1)}`, `  User ${session.account.slice(0, at)}`,
+    ...(session.port ? [`  Port ${session.port}`] : []),
     `  IdentityFile ${configPath(session.keyFile)}`, '  IdentitiesOnly yes', `  UserKnownHostsFile ${configPath(session.knownFile)}`,
     `  StrictHostKeyChecking ${session.strict}`, '  BatchMode yes', '  ConnectTimeout 20',
     ...(windows ? [] : controlLines(controlPath)), '',
@@ -102,7 +104,7 @@ export async function withDockerTransport(ctx, config, { sshCmd = null } = {}, b
     const baseEnv = session ? dockerEnvironment(ctx, session, controlPath) : ctx.env;
     const { env, executable } = privateSshEnvironment(ctx, baseEnv, dir, controlPath);
     const configFile = path.join(env.HOME ?? '', '.ssh', 'config');
-    const options = ['-o', 'BatchMode=yes', '-o', 'ConnectTimeout=20'];
+    const options = ['-o', 'BatchMode=yes', '-o', 'ConnectTimeout=20', ...(session?.port ? ['-p', String(session.port)] : [])];
     const argv = session || executable !== 'ssh' ? [executable, ...options, '-F', configFile, '--', alias] : ['ssh', ...options, '--', alias];
     connection = createSshSession(ctx, { argv, env, controlPath, cleanup });
     const spawn = dockerSpawn(ctx, connection, env, alias);

package/stack/remote.mjs

@@ -14,6 +14,7 @@ import { tool } from './context.mjs';
 import { restrictToUser, writePrivate } from './private-file.mjs';
 import { refusal } from './errors.mjs';
 import { createSshSession, sessionDirectory } from './ssh-session.mjs';
+import { assertStackAccount } from './target-binding.mjs';
 
 const ACCOUNT = /^[A-Za-z0-9._@-]+$/u;
 const CI_VARIABLES = ['VPS_SSH_KEY', 'VPS_KNOWN_HOSTS', 'VPS_HOST', 'VPS_USER'];
@@ -92,9 +93,12 @@ function writeWithMode(file, text, mode) {
 export function openSealedSession(ctx, config) {
   const { sealed } = config.remote;
   const account = opsAccount(ctx, config);
+  if (config.nativeTarget && account !== `${config.nativeTarget.user}@${config.nativeTarget.host}`)
+    throw refusal('STACK_REMOTE_OPS', 'the sealed SSH account differs from the accepted native target');
   const key = binaryMember(ctx, config, sealed.sshKey, ['privateKey', 'key']);
   if (!key.includes('PRIVATE KEY')) throw refusal('STACK_REMOTE_KEY', `${sealed.sshKey} does not hold a PEM private key`);
   const known = binaryMember(ctx, config, sealed.knownHosts, ['knownHosts', 'known_hosts']).trim();
+  assertStackAccount(config.nativeTarget, account, known);
   const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'stack-ssh-'));
   const keyFile = path.join(dir, 'id');
   const knownFile = path.join(dir, 'known_hosts');
@@ -113,13 +117,14 @@ export function openSealedSession(ctx, config) {
     throw error;
   }
   const notes = known ? [] : ['owner-machine session without known_hosts: the host key is accepted on first contact (accept-new); verify it, CI never does this'];
-  return { account, dir, keyFile, knownFile, strict: known ? 'yes' : 'accept-new', notes, cleanup };
+  return { account, dir, keyFile, knownFile, strict: known ? 'yes' : 'accept-new', notes, cleanup,
+    ...(config.nativeTarget ? { port: config.nativeTarget.port } : {}) };
 }
 
 /** The owner-machine runner over that session. */
 function sealedRunner(ctx, config) {
   const session = openSealedSession(ctx, config);
-  const argv = ['ssh', '-T', '-i', session.keyFile, '-o', 'IdentitiesOnly=yes', '-o', `UserKnownHostsFile=${session.knownFile}`, '-o', `StrictHostKeyChecking=${session.strict}`, '-o', 'BatchMode=yes', '-o', 'ConnectTimeout=20', session.account];
+  const argv = ['ssh', '-T', ...(session.port ? ['-p', String(session.port)] : []), '-i', session.keyFile, '-o', 'IdentitiesOnly=yes', '-o', `UserKnownHostsFile=${session.knownFile}`, '-o', `StrictHostKeyChecking=${session.strict}`, '-o', 'BatchMode=yes', '-o', 'ConnectTimeout=20', session.account];
   return sessionRunner(ctx, argv, session.dir, session.cleanup, session.notes);
 }
 
@@ -143,6 +148,7 @@ function sshRunner(ctx, config, { sshCmd = null } = {}) {
  */
 function withOwnerTransport(ctx, config, { sshCmd = null } = {}) {
   const { sealed } = config.remote;
+  if (config.nativeTarget) return Object.create(ctx, { env: { value: { ...ctx.env, STARCI_STACK_SEALED_SSH: '1' }, enumerable: true } });
   if (sshCmd || !sealed || ctx.env.GITHUB_ACTIONS === 'true' || ctx.env.STARCI_STACK_SEALED_SSH !== undefined) return ctx;
   const present = [sealed.ops, sealed.sshKey, sealed.knownHosts].every((slug) => fs.existsSync(path.join(config.secretsDir, `${slug}.enc`)));
   if (!present) return ctx;

package/stack/target-binding.mjs

@@ -0,0 +1,125 @@
+// Public endpoint assertions for admitted native consumers; this module never opens custody.
+import fs from 'node:fs';
+import path from 'node:path';
+import { refusal } from './errors.mjs';
+
+const slug = value => typeof value === 'string' && /^[a-z][a-z0-9-]*$/.test(value);
+const label = value => typeof value === 'string' && /^[A-Za-z0-9_][A-Za-z0-9_.-]*$/.test(value);
+const host = value => typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9.-]*$/.test(value);
+const port = value => Number.isInteger(value) && value > 0 && value <= 65535;
+const denied = () => { throw refusal('STACKS_DEPLOY_CONFIG_INVALID', 'the native endpoint binding is invalid or differs from the selected owner target'); };
+const exact = (value, fields) => value && typeof value === 'object' && !Array.isArray(value)
+  && Object.keys(value).length === fields.length && fields.every(key => Object.hasOwn(value, key));
+
+function ordinaryInput(root, file) {
+  if (typeof root !== 'string' || !path.isAbsolute(root)) denied();
+  const relative = path.relative(root, file);
+  if (!relative || path.isAbsolute(relative) || relative.split(path.sep).includes('..')) denied();
+  let current = root;
+  const parts = relative.split(path.sep);
+  for (let index = 0; index <= parts.length; index += 1) {
+    let stat;
+    try { stat = fs.lstatSync(current); } catch { denied(); }
+    if (stat.isSymbolicLink() || (index === parts.length ? !stat.isFile() || stat.nlink !== 1 : !stat.isDirectory())) denied();
+    if (index < parts.length) current = path.join(current, parts[index]);
+  }
+}
+
+/** A bound native owner opens only an ordinary envelope below its actual app, without ancestor links. */
+export const assertBoundCustody = (root, file) => ordinaryInput(root, file);
+
+/** Bound database commands require the app-local launcher; they cannot discover a global replacement. */
+export function boundSupabaseLauncher(root) {
+  const launcher = path.join(root, 'node_modules', 'supabase', 'dist', 'supabase.js');
+  ordinaryInput(root, launcher);
+  return launcher;
+}
+
+/** Native custody can use AGE; tools that do not decrypt custody must not inherit that identity. */
+export function nativeToolEnvironment(env) {
+  return Object.fromEntries(Object.entries(env).filter(([key]) => !/^SOPS_/i.test(key)));
+}
+
+/** Bound database tools receive only their selected private password and native routing, without ambient libpq or provider credentials. */
+export function nativeDatabaseEnvironment(env, binding, selected = {}, omit = []) {
+  const omitted = new Set(omit.filter(value => typeof value === 'string').map(value => value.toUpperCase()));
+  return { ...Object.fromEntries(Object.entries(nativeToolEnvironment(env)).filter(([key]) => !/^(?:PG[A-Z_]*|SUPABASE_)/i.test(key) && !omitted.has(key.toUpperCase()))),
+    'SUPABASE_ENV': binding.environment, ...selected };
+}
+
+/** Preserve a logical linked project while selecting a fixed native SQL endpoint without the CLI's linked Management finalizer. */
+export function boundLinkedDatabaseUrl(binding, savedPooler = null) {
+  if (!binding || binding.mode !== 'linked' || !/^[a-z0-9]{20}$/.test(binding.projectRef)) denied();
+  if (savedPooler === null) return `postgresql://postgres@db.${binding.projectRef}.supabase.co:5432/postgres?sslmode=require`;
+  let url;
+  try {
+    if (typeof savedPooler !== 'string' || savedPooler.length > 8192) denied();
+    url = new URL(savedPooler.trim());
+    if (!['postgres:', 'postgresql:'].includes(url.protocol) || !/^[A-Za-z0-9.-]+\.pooler\.supabase\.com$/.test(url.hostname)
+      || decodeURIComponent(url.username) !== `postgres.${binding.projectRef}` || url.pathname !== '/postgres'
+      || url.port && !['5432', '6543'].includes(url.port) || url.hash
+      || [...url.searchParams].some(([key, value]) => key !== 'sslmode' || !['require', 'verify-full'].includes(value))) denied();
+  } catch { denied(); }
+  url.password = '';
+  url.port = '5432';
+  if (!url.searchParams.has('sslmode')) url.searchParams.set('sslmode', 'require');
+  return url.toString();
+}
+
+/** Parse the internal public binding; ordinary commands without this flag retain their native behavior. */
+export function parseTargetBinding(text, kind) {
+  if (text === undefined) return null;
+  let binding;
+  try { if (typeof text !== 'string' || text.length > 4096) denied(); binding = JSON.parse(text); } catch { denied(); }
+  if (binding?.kind !== kind || !slug(binding.environment)) denied();
+  if (kind === 'docker-swarm') {
+    if (!exact(binding, ['kind', 'environment', 'stack', 'host', 'user', 'port']) || !slug(binding.stack)
+      || !host(binding.host) || !label(binding.user) || binding.port !== 22) denied();
+  } else if (kind === 'supabase-db') {
+    if (binding.mode === 'local') {
+      if (!exact(binding, ['kind', 'mode', 'environment', 'localProject', 'port']) || !label(binding.localProject) || !port(binding.port)) denied();
+    } else if (binding.mode === 'linked') {
+      if (!exact(binding, ['kind', 'mode', 'environment', 'projectRef']) || !/^[a-z0-9]{20}$/.test(binding.projectRef ?? '')) denied();
+    } else if (binding.mode === 'url-env') {
+      if (!exact(binding, ['kind', 'mode', 'environment', 'urlEnv', 'host', 'port', 'database', 'user'])
+        || !/^[A-Z][A-Z0-9_]*$/.test(binding.urlEnv ?? '') || !host(binding.host) || !port(binding.port)
+        || !label(binding.database) || !label(binding.user)) denied();
+    } else denied();
+  } else denied();
+  return Object.freeze(binding);
+}
+
+/** Require the selected sealed transport before any fallback can reach an operator's Docker or SSH context. */
+export function bindStackTarget(ctx, config, binding) {
+  if (!binding) return config;
+  if (binding.kind !== 'docker-swarm' || binding.environment !== config.env || binding.stack !== config.stack
+    || !config.remote.sealed || ctx.env.DOCKER_HOST || ctx.env.DOCKER_CONTEXT || ctx.env.GITHUB_ACTIONS
+    || ctx.env.STARCI_STACK_SEALED_SSH !== undefined) denied();
+  for (const member of Object.values(config.remote.sealed)) {
+    const file = path.join(config.secretsDir, `${member}.enc`);
+    assertBoundCustody(config.repoRoot, file);
+  }
+  return { ...config, nativeTarget: binding };
+}
+
+/** Compare the effective private SSH account before key files, sessions or network effects exist. */
+export function assertStackAccount(binding, account, knownHosts) {
+  if (!binding) return;
+  if (account !== `${binding.user}@${binding.host}` || binding.port !== 22 || !knownHosts.trim()) denied();
+}
+
+/** Compare the effective local Supabase identity after its existing config/environment resolver. */
+export function assertLocalDatabase(binding, target) {
+  if (binding && (binding.mode !== 'local' || binding.localProject !== target.project || binding.port !== target.port)) denied();
+}
+
+/** Refuse a selected URL unless its non-secret endpoint exactly matches the accepted target. */
+export function assertUrlDatabase(binding, value) {
+  if (!binding) return;
+  let url;
+  try { url = new URL(value); } catch { denied(); }
+  if (binding.mode !== 'url-env' || !['postgres:', 'postgresql:'].includes(url.protocol)
+    || url.hostname !== binding.host || Number(url.port || '5432') !== binding.port
+    || decodeURIComponent(url.username) !== binding.user || decodeURIComponent(url.pathname.slice(1)) !== binding.database
+    || url.search || url.hash || !url.password) denied();
+}