@xeplr/workflow 1.0.1

package/lib/actions/screenShow.js

@@ -0,0 +1,55 @@
+// screen-show — PARK THE RUN AND LET A PERSON FILL IN A SCREEN.
+//
+// The step behind every node of a 'screens' flow (see lib/flows.js). It is a
+// `wait` step whose action does nothing at all, and the nothing is the whole
+// design:
+//
+//   1. the engine mints the resume key BEFORE the action runs (see
+//      workflowRunner's executeFrom) and parks the run at status 'waiting';
+//   2. this returns immediately, so there is nothing to undo and nothing that
+//      can fail between "the person opened the screen" and "the run is
+//      waiting for them";
+//   3. the person submits; POST /flows/runs/:runId/submit resumes the step
+//      with what they typed, and resumeByKey MERGES that onto this output.
+//
+// ── why it returns {} and not { screen } ─────────────────────────────────
+//
+// The step's output IS the submitted values, and nothing else. Transitions on
+// a screens flow read `output.<field>` where <field> is a field of the screen,
+// so anything this action put in the output would occupy a name a screen might
+// legitimately use — a screen with a field called `screen` would then branch on
+// this action's own bookkeeping until the moment it was submitted.
+//
+// Which screen was shown is not lost by returning nothing: the resolved input
+// is persisted on the step run (workflow_step_runs.input), so history records
+// it, and the facade reads the screen off the STEP row (values.screen) rather
+// than off a run, because that is where the flow's design lives.
+//
+// ── why it is not in the action palette ──────────────────────────────────
+//
+// It is registered (the engine resolves a step's actionName through the
+// registry, so a step could not run without it) but hidden from GET /actions —
+// see lib/actionCatalog.js's HIDDEN. Dropping one onto the ordinary workflow
+// canvas would produce a step that parks forever: nothing outside the flows
+// facade knows how to show a screen or how to resume it.
+
+module.exports = {
+  name: 'screen-show',
+  description: 'Show a screen to a person and wait for them to submit it. The values they ' +
+               'submit become this step\'s output, so a transition can branch on them.',
+  requires: [],
+
+  inputSchema: [
+    { name: 'screen', type: 'string', required: true, order: 1,
+      description: 'Key of the screen to show. The app that owns the screens resolves it; ' +
+                   'this engine only carries it.' }
+  ],
+
+  // Whatever the person submitted, which is not knowable from here — declared
+  // as nothing rather than as a lie. See the note above.
+  outputSchema: null,
+
+  execute: async function() {
+    return {};
+  }
+};

package/lib/db.js

@@ -0,0 +1,82 @@
+var { getConnection, registerMTs } = require('@xeplr/db');
+var models = require('../models');
+
+var _registered = false;
+var _conn = null;
+
+/**
+ * Bind workflow's own models to a connection. Config-driven — never reads
+ * process.env; that is orchestration/standalone.js's job when nothing else
+ * supplies one.
+ *
+ * @param {object} config
+ * @param {string} config.name - database name (workflow's OWN domain data —
+ *   this is always workflow's responsibility, embedded or standalone; that
+ *   data belongs to workflow, not whatever it's mounted into)
+ * @param {string} config.connection - connection string/encrypted blob, same
+ *   shape @xeplr/db's getConnection already expects
+ * @param {object} [config.mts] - { l1: {name, header}, ... }. registerMTs()
+ *   is PROCESS-GLOBAL — only pass this when nothing else in this process has
+ *   already called it. A host app embedding workflow has already registered
+ *   its own levels; passing config.mts in that case would silently overwrite
+ *   them. Standalone mode passes it; registerWorkflow's embedded branch does
+ *   not.
+ */
+async function connectDb(config) {
+  config = config || {};
+  if (!config.name || !config.connection) {
+    throw new Error('connectDb: { name, connection } are required');
+  }
+  if (config.mts && !_registered) {
+    registerMTs(config.mts);
+    _registered = true;
+  }
+
+  // bind:false — A SECONDARY CONNECTION, never the process's global one.
+  //
+  // @xeplr/db's bindModels does `Model.knex(instance)` on OBJECTION'S BASE
+  // CLASS, so it is global: the last getConnection with bind:true wins for
+  // every model in the process, whoever declared it. Standalone that is
+  // harmless, because workflow is the only thing here. Embedded it is not —
+  // connecting to workflow's own database re-pointed the HOST's models at it
+  // too, and the host's own routes started failing on tables that were never
+  // in this database.
+  //
+  // So workflow binds its OWN models to its OWN connection and leaves the
+  // global binding alone. Exactly what @xeplr/auth's attach() does to reach
+  // the auth database from the api process, and what @xeplr/actions'
+  // attachConfig() does for xeplr_configs — this is the third instance of the
+  // same shape, not a new idea.
+  _conn = await getConnection(config.name, config.connection, {
+    bind: false,
+    connectionName: config.connectionName || 'workflow'
+  });
+  return _conn;
+}
+
+function conn() {
+  if (!_conn) throw new Error('workflow: connection not ready — await connectDb() first');
+  return _conn;
+}
+
+/**
+ * A workflow model BOUND to workflow's own connection.
+ *
+ * Every query in this package goes through here rather than through the class
+ * exported by models/index.js. An unbound class falls back to the global
+ * binding, which belongs to whatever else is in this process — the host app,
+ * embedded — so it would read the wrong database and mostly report that
+ * workflow's tables do not exist.
+ *
+ * Objection caches per (Model, knex) pair, so calling this per request costs a
+ * map lookup rather than a new class.
+ */
+function model(name) {
+  var M = models[name];
+  if (!M) throw new Error('workflow: unknown model "' + name + '"');
+  return M.bindKnex(conn());
+}
+
+module.exports = connectDb;
+module.exports.conn = conn;
+module.exports.model = model;

package/lib/envExposed.js

@@ -0,0 +1,87 @@
+// WHICH ENV VARS A WORKFLOW STEP MAY REFERENCE, as `{env.NAME}`.
+//
+// Nothing, unless named:
+//
+//   WORKFLOW_ENV_EXPOSED=PUBLIC_BASE_URL,DEPLOY_TAG
+//
+// AN ALLOWLIST, NOT A DENYLIST, and that is the whole design. A denylist works
+// on the day it is written and fails silently afterwards: the day somebody
+// adds STRIPE_SECRET_KEY to the environment it is readable until a second
+// person remembers to go and hide it. This way a new variable is invisible
+// until it is deliberately published, so the failure mode of forgetting is
+// "the template renders empty" rather than "the key leaked".
+//
+// WHY THIS MATTERS MORE THAN IT LOOKS. A resolved step input is not private:
+//
+//   - POST /workflows/:id/steps/try ECHOES the interpolated input straight
+//     back to the browser, by design, so the builder can show what it sent
+//     (see lib/router.js). The step does not even have to be saved — `values`
+//     comes off the request body.
+//   - workflowRunner writes the resolved values into WorkflowStepRun.input,
+//     where they stay for the life of the run history.
+//
+// So without a list, "can author a workflow step" would silently mean "can
+// read ENCRYPTION_KEY and AUTH_JWT_SECRET" — the two that decrypt every
+// stored connection string and mint a token for any user. Both halves of that
+// escalation look ordinary in an access-control table, which is exactly why
+// it has to be shut off here rather than noticed later.
+//
+// KEEP SECRETS OFF THIS LIST. It is for values that are awkward to hardcode
+// per environment and harmless to read: a public base URL, an environment
+// tag, a bucket name. A credential belongs on the path where the ACTION reads
+// it server-side at execution time and it never enters the template context
+// at all — that is what `useCustomConnection: false` on the email actions
+// does with SMTP_*, and it is strictly safer than any list.
+
+// Exact names only. No prefixes and no globs: `PUBLIC_*` reads as a small
+// convenience right up until somebody names a secret PUBLIC_something, and
+// then the list no longer says what it exposes. A literal '*' matches a
+// variable actually called '*', which does not exist — so the tempting
+// shortcut fails closed rather than exposing everything.
+function exposedNames() {
+  var raw = process.env.WORKFLOW_ENV_EXPOSED;
+  if (!raw) return [];
+  return String(raw).split(',')
+    .map(function(n) { return n.trim(); })
+    .filter(function(n) { return n.length > 0; });
+}
+
+/**
+ * The `env` branch of a step's interpolation context.
+ *
+ * Read per call rather than memoized at load: this module is required before
+ * the host has finished loading its .env in at least one boot order, and a
+ * snapshot taken then would be permanently empty with nothing to explain it.
+ * The cost is splitting a short string once per step.
+ *
+ * A name on the list that is not set is OMITTED rather than included as
+ * undefined — either way `{env.NAME}` renders as empty string, since that is
+ * what interpolate() does with any unknown path (see @xeplr/schema-handler's
+ * templating.js). Worth knowing when debugging: a misspelled name and an
+ * unexposed one look identical in the output.
+ */
+function exposedEnv() {
+  var out = {};
+  exposedNames().forEach(function(name) {
+    if (process.env[name] !== undefined) out[name] = process.env[name];
+  });
+  return out;
+}
+
+/**
+ * Say at boot what is readable, so it is a fact in the log rather than a
+ * thing you would have to go and derive from an .env file. A list that
+ * accidentally names a secret is only catchable if somebody can see it.
+ */
+function logExposure() {
+  var names = exposedNames();
+  if (!names.length) return;
+  var missing = names.filter(function(n) { return process.env[n] === undefined; });
+  console.log('[workflow] {env.*} exposes ' + names.length + ' var(s) to step templates: ' + names.join(', '));
+  if (missing.length) {
+    console.warn('[workflow] WORKFLOW_ENV_EXPOSED names ' + missing.length +
+      ' var(s) that are not set (they resolve to empty string): ' + missing.join(', '));
+  }
+}
+
+module.exports = { exposedNames: exposedNames, exposedEnv: exposedEnv, logExposure: logExposure };