@factiii/runner 0.10.2 → 0.11.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@factiii/runner",
-  "version": "0.10.2",
+  "version": "0.11.1",
   "description": "Factiii Runner, run Board AI agents on a machine you control. Pairs with the Factiii web/mobile clients over WebRTC.",
   "license": "ISC",
   "keywords": [

package/plugin/factiii/bin/factiii-secrets

@@ -0,0 +1,208 @@
+#!/usr/bin/env node
+/**
+ * factiii-secrets - run a command with this space's stored secrets injected.
+ *
+ * A PROXY, never a carrier. This process asks the runner to run the command;
+ * the runner is what holds the decrypted values, execs the command, and sends
+ * back output already redacted against them. Nothing secret ever enters this
+ * process, so nothing secret is visible to whatever spawned it - which is the
+ * whole point, because what spawns it is an AI agent.
+ *
+ * Finding the runner doubles as the gate: this plugin installs globally, so
+ * outside a factiii space there is no socket and the command says so rather
+ * than hanging.
+ */
+'use strict';
+
+const fs = require('fs');
+const net = require('net');
+const path = require('path');
+
+const SOCK_NAME = 'secrets.sock';
+/** Denial is not a command failure: a distinct code lets a script tell "the
+ *  owner said no" from "the command ran and failed". */
+const EXIT_DENIED = 77;
+/** Nothing ran at all - no socket, no runner, bad usage. */
+const EXIT_UNAVAILABLE = 3;
+
+function usage() {
+  process.stderr.write(
+    [
+      'usage:',
+      '  factiii-secrets run -- <command...>   run it with the declared secrets injected',
+      '  factiii-secrets list                  print the declared key NAMES (never values)',
+      ''
+    ].join('\n')
+  );
+}
+
+/** `<spaceDir>/state/secrets.sock`. The env var is what the runner sets on
+ *  every spawn; the walk-up covers a caller that changed the working
+ *  directory to somewhere the runner did not choose. */
+function findSocket() {
+  const fromEnv = process.env.FACTIII_SECRETS_SOCK;
+  if (fromEnv) return fromEnv;
+  let dir = process.cwd();
+  while (dir && dir !== path.dirname(dir)) {
+    const candidate = path.join(dir, 'state', SOCK_NAME);
+    try {
+      if (fs.statSync(candidate).isSocket()) return candidate;
+    } catch {
+      // Not here; keep walking.
+    }
+    dir = path.dirname(dir);
+  }
+  return null;
+}
+
+/**
+ * Rebuild one shell word.
+ *
+ * The runner runs the command through a login shell and shows it to the owner
+ * verbatim for authorization, so what we send has to mean exactly what the
+ * caller's argv meant. Single quotes make every character literal; the only
+ * thing that cannot appear inside them is a single quote, which is spliced.
+ * Words that need no quoting are left bare so the authorization card stays
+ * readable.
+ */
+function shellQuote(word) {
+  if (/^[A-Za-z0-9_@%+=:,./-]+$/.test(word)) return word;
+  return `'${word.split("'").join(`'\\''`)}'`;
+}
+
+/** One NDJSON request, its stream of replies handled by `onMessage`. */
+function request(socketPath, payload, onMessage) {
+  return new Promise((resolve) => {
+    const conn = net.createConnection(socketPath);
+    let buffer = '';
+    let settled = false;
+    const finish = (code) => {
+      if (settled) return;
+      settled = true;
+      conn.end();
+      resolve(code);
+    };
+
+    conn.on('connect', () => conn.write(`${JSON.stringify(payload)}\n`));
+    conn.on('data', (chunk) => {
+      buffer += chunk.toString('utf-8');
+      let newline = buffer.indexOf('\n');
+      while (newline !== -1) {
+        const line = buffer.slice(0, newline);
+        buffer = buffer.slice(newline + 1);
+        if (line.trim()) {
+          let message;
+          try {
+            message = JSON.parse(line);
+          } catch {
+            // A malformed frame is the runner's bug, not the caller's; there
+            // is nothing useful to do with half a message.
+            message = null;
+          }
+          if (message) {
+            const code = onMessage(message);
+            if (typeof code === 'number') finish(code);
+          }
+        }
+        newline = buffer.indexOf('\n');
+      }
+    });
+    conn.on('error', (err) => {
+      // The path can be known and still have nothing listening: the store is
+      // served only while a deploy run is in progress, and a creator session
+      // drafting a skill is the common case of asking outside one.
+      const why =
+        err.code === 'ENOENT' || err.code === 'ECONNREFUSED'
+          ? 'the secrets store is not being served right now. It is available during a deploy run'
+          : `cannot reach the runner (${err.message})`;
+      process.stderr.write(`factiii-secrets: ${why}.\n`);
+      finish(EXIT_UNAVAILABLE);
+    });
+    // Closed with no verdict: the runner died, or the deploy run was
+    // cancelled mid-command. Either way nothing was reported as finished.
+    conn.on('close', () => finish(EXIT_UNAVAILABLE));
+  });
+}
+
+async function main() {
+  const [op, ...rest] = process.argv.slice(2);
+
+  if (!op || op === '-h' || op === '--help') {
+    usage();
+    return op ? 0 : EXIT_UNAVAILABLE;
+  }
+  if (op !== 'run' && op !== 'list') {
+    process.stderr.write(`factiii-secrets: unknown command "${op}".\n`);
+    usage();
+    return EXIT_UNAVAILABLE;
+  }
+
+  const socketPath = findSocket();
+  if (!socketPath) {
+    process.stderr.write(
+      'factiii-secrets: no secrets store is reachable here. This command works inside a factiii space while a deploy run is active.\n'
+    );
+    return EXIT_UNAVAILABLE;
+  }
+
+  if (op === 'list') {
+    return request(socketPath, { op: 'list' }, (message) => {
+      if (message.type === 'keys') {
+        process.stdout.write(`${message.keys.join('\n')}\n`);
+        return 0;
+      }
+      if (message.type === 'error') {
+        process.stderr.write(`factiii-secrets: ${message.message}\n`);
+        return EXIT_UNAVAILABLE;
+      }
+    });
+  }
+
+  // `--` is optional but documented: it is what stops the caller's own flags
+  // (-e, --prod) from being read as ours.
+  const argv = rest[0] === '--' ? rest.slice(1) : rest;
+  if (!argv.length) {
+    process.stderr.write('factiii-secrets: run needs a command.\n');
+    usage();
+    return EXIT_UNAVAILABLE;
+  }
+
+  const command = argv.map(shellQuote).join(' ');
+  return request(
+    socketPath,
+    { op: 'run', command, cwd: process.cwd() },
+    (message) => {
+      if (message.type === 'status') {
+        // stderr, so a caller capturing stdout gets the command's output and
+        // nothing of ours.
+        process.stderr.write(`factiii-secrets: ${message.text}\n`);
+        return;
+      }
+      if (message.type === 'output') {
+        process.stdout.write(message.chunk);
+        return;
+      }
+      if (message.type === 'denied') {
+        process.stderr.write(
+          'factiii-secrets: the owner declined to run that command.\n'
+        );
+        return EXIT_DENIED;
+      }
+      if (message.type === 'error') {
+        process.stderr.write(`factiii-secrets: ${message.message}\n`);
+        return EXIT_UNAVAILABLE;
+      }
+      if (message.type === 'exit') return message.code;
+    }
+  );
+}
+
+main().then(
+  (code) => {
+    process.exitCode = code;
+  },
+  (err) => {
+    process.stderr.write(`factiii-secrets: ${err && err.message}\n`);
+    process.exitCode = EXIT_UNAVAILABLE;
+  }
+);

package/plugin/factiii/skills/factiii-secrets/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: factiii-secrets
+description: Run a command that needs this workspace's stored secrets, with factiii-secrets. TRIGGER when a command needs an API token, deploy credential, database URL or any other secret value, when writing or revising a deploy skill, or whenever an environment variable a step needs appears to be missing.
+---
+
+# factiii-secrets
+
+This machine keeps the workspace's secrets in an encrypted store the owner
+manages. You never hold those values, and you never need to: one command runs
+anything that needs them.
+
+```bash
+factiii-secrets run -- <command...>
+```
+
+It is already on your PATH. Nothing needs installing, and nothing needs
+setting up before you use it.
+
+## What actually happens
+
+You run the command. It blocks. The owner sees the exact command on their
+board, with the keys it will receive, and enters their password to authorize
+it. The runner then decrypts the store for that one command, runs it with the
+values in its environment, and hands you back its output with every secret
+value replaced by `[REDACTED]`. `factiii-secrets` exits with the command's own
+exit code, so `&&`, `||` and `set -e` all behave normally.
+
+The values reach the command and stop there. They are never in your
+environment, never in your context, and never in anything you can read.
+
+## Using it
+
+Write the command exactly as you would without the wrapper, referencing
+secrets as ordinary `$NAME` variables:
+
+```bash
+factiii-secrets run -- vercel deploy --prod --token "$VERCEL_TOKEN"
+factiii-secrets run -- psql "$DATABASE_URL" -f migrations/latest.sql
+factiii-secrets run -- ./scripts/publish.sh
+```
+
+Quote the variables. They expand on the runner's side, once the values are
+present - not in your shell, where they are empty.
+
+Wrap **only** the commands that need a secret. Everything else - builds,
+tests, git, file edits - runs normally, unwrapped, and stays fast because it
+needs no authorization.
+
+```bash
+factiii-secrets list
+```
+
+prints the key NAMES the workspace has declared. Never their values; there is
+no command that prints a value, on purpose.
+
+## Things that will waste your time
+
+- **Do not check whether these variables are set.** They are unset in your
+  shell by design and will stay that way for the whole session. `env`,
+  `printenv`, `test -n "$TOKEN"` and echo-checks all tell you nothing.
+- **Do not report them as missing or stop over them.** An unset declared
+  variable is the security model working. Route the command through
+  `factiii-secrets run` and it gets what it needs.
+- **Do not ask the owner to export them,** write them to a `.env`, or put them
+  in a shell profile or CI config. They are already stored; that is what this
+  command reads.
+- **Never print a value.** If output somehow contains one, do not repeat it.
+
+## Exit codes
+
+- The command's own exit code, when it ran.
+- `77` - the owner declined to authorize it. That is an answer, not a fault:
+  adapt or stop and explain where things stand. Do not retry the same command.
+- `3` - nothing ran. No store is reachable here, or the runner went away.
+
+## Writing a deploy skill
+
+A repo's deploy skill declares every key it needs in
+`.agents/skills/deploy/required-variables.json`, then wraps each step that
+needs one in `factiii-secrets run -- …`. Declare a key exactly when a command
+uses it: never declare one the skill does not use, never use one it does not
+declare. Put no secret value, and no key material, in any file.