@flow-engineer/flow 0.3.3 → 0.4.1

package/dist/src/business-events/signature.js

@@ -0,0 +1,36 @@
+// Flow-Signature on a business's pushed events: `t=<unix seconds>,v1=<hex HMAC-SHA256>` of
+// "t.{t}.{raw body}", with the secret the business was given (whsec_...). t may be at most 5 minutes
+// off. Several v1 values are allowed, so a secret can be rotated without dropping events.
+import { createHmac, timingSafeEqual } from "node:crypto";
+/** How far a signature's `t` may be from now. */
+export const SIGNATURE_TOLERANCE_MS = 5 * 60_000;
+/** The hex HMAC for `t` (unix seconds) and the raw body. */
+export function eventSignature(secret, t, body) {
+    return createHmac("sha256", secret).update(`t.${t}.${body}`).digest("hex");
+}
+/** The Flow-Signature header for this body, signed now (ms since the epoch). */
+export function signEvent(secret, body, now = Date.now()) {
+    const t = Math.floor(now / 1000);
+    return `t=${t},v1=${eventSignature(secret, t, body)}`;
+}
+/** Whether the header signs this body with this secret, at most 5 minutes from `now` (ms). */
+export function verifyEventSignature(secret, header, body, now = Date.now()) {
+    if (!header)
+        return false;
+    let t = null;
+    const v1 = [];
+    for (const part of header.split(",")) {
+        const [k, v] = part.trim().split("=", 2);
+        if (k === "t" && v && /^\d+$/.test(v))
+            t = Number(v);
+        else if (k === "v1" && v)
+            v1.push(v);
+    }
+    if (t === null || !v1.length || Math.abs(now - t * 1000) > SIGNATURE_TOLERANCE_MS)
+        return false;
+    const want = Buffer.from(eventSignature(secret, t, body), "hex");
+    return v1.some((s) => {
+        const got = Buffer.from(s, "hex");
+        return got.length === want.length && timingSafeEqual(got, want);
+    });
+}

package/dist/src/business-events/testlist.d.ts

@@ -0,0 +1,15 @@
+export interface EventTestList {
+    /** Whether a business-started send may go to this address. */
+    allows(address: string): boolean;
+    /** Whether a list applies at all (false on production). */
+    enforced: boolean;
+}
+/** The numbers in a comma-separated list: spaces dropped, anything not E.164 left out. */
+export declare function parseTestNumbers(value: string | undefined): string[];
+export declare function eventTestList(options?: {
+    env?: Record<string, string | undefined>;
+    variable?: string;
+    numbers?: string[];
+    testing?: boolean;
+    madeUp?: RegExp;
+}): EventTestList;

package/dist/src/business-events/testlist.js

@@ -0,0 +1,24 @@
+// The test list: off production, a send the business starts (an event's message, a nudge, a held
+// send when it comes due) goes only to addresses on it, so a staging copy of real data never
+// reaches a real customer. Replies to people who wrote first are never checked here.
+//
+// - FLOW_ENVIRONMENT=production: no list, everyone.
+// - Otherwise: the numbers in `variable` (default FLOW_TEST_NUMBERS; comma-separated E.164, spaces
+//   fine, anything else ignored), or `numbers`; none sends nothing (fail closed).
+// - `testing` adds the addresses `madeUp` matches (a test run's made-up numbers).
+const E164 = /^\+\d{8,15}$/;
+/** The numbers in a comma-separated list: spaces dropped, anything not E.164 left out. */
+export function parseTestNumbers(value) {
+    return (value ?? "")
+        .split(",")
+        .map((n) => n.replace(/\s+/g, ""))
+        .filter((n) => E164.test(n));
+}
+export function eventTestList(options = {}) {
+    const env = options.env ?? process.env;
+    if (env.FLOW_ENVIRONMENT === "production")
+        return { enforced: false, allows: () => true };
+    const listed = new Set(options.numbers ? parseTestNumbers(options.numbers.join(",")) : parseTestNumbers(env[options.variable ?? "FLOW_TEST_NUMBERS"]));
+    const madeUp = options.madeUp;
+    return { enforced: true, allows: (address) => listed.has(address) || (options.testing === true && madeUp !== undefined && madeUp.test(address)) };
+}

package/dist/src/index.d.ts

@@ -13,3 +13,4 @@ export type { TracesOptions } from "./traces.ts";
 export { tool, toSpec, type ChatAuth, type ChatAuthContext, type CredentialProvider, type Credentials, type SignIn, type Tool, type ToolContext, type ToolHints } from "./tools.ts";
 export type { Attachment, ChannelInfo, ChatMessage, Deliver, Incoming, ListRow, Media, Model, ModelRequest, ModelResponse, Outbound, PersonMessage, Template, TemplateButton, TemplateDefinition, ToolCall, ToolSpec, Transcribe } from "./types.ts";
 export { z } from "zod";
+export * from "./business-events/index.ts";

package/dist/src/index.js

@@ -10,3 +10,4 @@ export { flowModel, flowModelURL, openAICompatible } from "./model.js";
 export { Store } from "./store.js";
 export { tool, toSpec } from "./tools.js";
 export { z } from "zod";
+export * from "./business-events/index.js";

package/dist/testing/src/account.js

@@ -61,6 +61,8 @@ Exit status: 0 done, 1 usage or not signed in, 2 network, 3 refused, denied or e
 4 still waiting for approval (run ${RUN} login --wait), or flow.engineer asked to wait (try again after the time it gives).`;
 const NEXT = { login: `${RUN} login`, wait: `${RUN} login --wait`, setup: `${RUN} setup`, link: `${RUN} link` };
 const CHANNELS = ["telegram", "whatsapp", "imessage"];
+/** After link and status: the step that keeps the agent answering once this machine sleeps. */
+const DEPLOY_HINT = `To keep it answering while this machine sleeps: ${RUN} deploy (Flow's hosting, staging first).`;
 const EXIT = { ok: 0, usage: 1, network: 2, refused: 3, pending: 4 };
 class Stop extends Error {
     code;
@@ -824,6 +826,7 @@ async function status(json, out, say) {
     }
     if (next.length)
         say(`Next: ${next.join(", then ")}`);
+    say(DEPLOY_HINT);
 }
 /**
  * status's model line. Flow's key the active one: its credit from GET /credit. A key Flow does not
@@ -982,6 +985,7 @@ async function link(options, json, out, say) {
         if (REPLY_ONLY[c])
             say(REPLY_ONLY[c]);
     say(`Next: ${next.join(", then ")}.`);
+    say(DEPLOY_HINT);
 }
 /**
  * Asks flow.engineer's /try page for its direct link as JSON ({"channel", "message", "link", "page"}):

package/dist/testing/src/business.js

@@ -3,7 +3,8 @@
 // cloud's commands move and with copies of the agent's own channels, so its sends go through what
 // the agent wraps around them and come to the cloud with the run's time. The person writes through
 // agent.message(), as a provider's webhook would, so they are a person the agent can nudge.
-import { createHmac, randomBytes } from "node:crypto";
+import { randomBytes } from "node:crypto";
+import { signEvent } from "../../src/index.js";
 /** One minute: the clock moves this far at a time, and what came due runs at each step. */
 export const STEP_MS = 60_000;
 export function businessRuns(ctx) {
@@ -56,11 +57,10 @@ export function businessRuns(ctx) {
     };
     const event = async (run, command) => {
         const body = JSON.stringify(command.envelope);
-        const t = Math.floor(run.clock / 1000);
         const secret = command.signature === "bad" ? `whsec_test_${randomBytes(18).toString("hex")}` : run.secret;
         const headers = { "content-type": "application/json", "idempotency-key": command.envelope.id };
         if (command.signature !== "missing")
-            headers["flow-signature"] = `t=${t},v1=${createHmac("sha256", secret).update(`t.${t}.${body}`).digest("hex")}`;
+            headers["flow-signature"] = signEvent(secret, body, run.clock);
         const response = await run.agent.fetch(new Request(`http://agent.test${command.path ?? "/v1/events"}`, { method: "POST", headers, body }));
         const text = await response.text();
         let parsed = text;

package/dist/testing/src/cli.js

@@ -17,7 +17,8 @@
 // scenarios that did not pass. --json prints one report (testing/src/report.ts) on stdout at every exit,
 // and `flow show <run>` prints one run's record from the cloud (testing/src/show.ts).
 // `flow login`, `logout`, `whoami`, `setup` and `link` sign in to flow.engineer and get the agent's
-// keys and its phone link (testing/src/account.ts).
+// keys and its phone link (testing/src/account.ts). `flow deploy` puts the agent on Flow's hosting
+// (testing/src/deploy.ts).
 var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
     if (typeof path === "string" && /^\.\.?\//.test(path)) {
         return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
@@ -41,6 +42,7 @@ import { checkEndpointCli } from "./check-endpoint.js";
 import { CHECK_LINE as TOOLS_CHECK_LINE, checkCli, mcpUpdateCli } from "./check.js";
 import { ACCOUNT_COMMANDS, ACCOUNT_LINES, accountCli } from "./account.js";
 import { CHAT_LINE, chatCli } from "./chat.js";
+import { DEPLOY_LINE, deployCli, logsCli } from "./deploy.js";
 import { httpAgent } from "./http-agent.js";
 import { createInterface } from "node:readline/promises";
 import { displayNameOf, folderName, initHere, newStandalone, packageRoot } from "./new.js";
@@ -119,7 +121,7 @@ the CHINWAG_ names from before the rename still work):
                            (the agent's Flow key, on its trial credit; flow setup writes it)`;
 const TEST_USAGE = `Usage:\n${TEST_LINE}\n\n${TEST_OPTIONS}`;
 const USAGE = `Usage:\n${NEW_LINE}\n${CHAT_LINE}\n${TEST_LINE}\n${SHOW_LINE}\n${CHECK_LINE}\n${TOOLS_CHECK_LINE}\n${MCP_LINE}\n${CLI_LINE}
-${PLUGIN_LINE}\n${ACCOUNT_LINES}\n  flow --version         Show the version\n\n${TEST_OPTIONS}`;
+${PLUGIN_LINE}\n${ACCOUNT_LINES}\n${DEPLOY_LINE}\n  flow --version         Show the version\n\n${TEST_OPTIONS}`;
 /** What to do after new or init, from step 2; a model key comes first when none is set here. */
 function nextSteps() {
     // link signs in and writes the keys first, FLOW_KEY (the model, on Flow's free trial credit) among
@@ -155,6 +157,10 @@ if (process.argv[2] === "cli") {
     const { defineCli, runCli } = await import("../../cli/src/index.js");
     process.exit(await runCli(defineCli({ name: "flow" }), process.argv.slice(3)));
 }
+if (process.argv[2] === "deploy")
+    process.exit(await deployCli(process.argv.slice(3)));
+if (process.argv[2] === "logs")
+    process.exit(await logsCli(process.argv.slice(3)));
 if (process.argv[2] === "chat")
     process.exit(await chatCli(process.argv.slice(3)));
 if (ACCOUNT_COMMANDS.has(process.argv[2] ?? ""))

package/dist/testing/src/deploy.d.ts

@@ -0,0 +1,36 @@
+export declare const DEPLOY_LINE = "  flow deploy [--env staging|production] [--dir <folder>] [--version <v>] [--no-secrets] [--json]\n                            Put this agent on Flow's hosting, so it answers while this machine\n                            sleeps (flow deploy --help: status, promote, secret, secrets)\n  flow logs [--env staging|production] [--since 1h] [--follow] [--json]\n                            The hosted agent's recent log lines";
+export declare const LOGS_USAGE = "Usage:\n  flow logs [--env staging|production] [--since 1h] [--follow] [--json]\n\n  --env        Which (default: staging).\n  --since      How far back: 30s, 15m, 1h (the default) or 2d, at most 30d.\n  --follow     Keep printing new lines until Ctrl-C.\n  --json       One JSON object per line on stdout: { time, severity, text }.\n  --dir, --cloud, FLOW_FRAMEWORK_CLOUD_KEY: as for flow deploy (flow deploy --help).";
+export declare const DEPLOY_USAGE = "Usage:\n  flow deploy [--env staging|production] [--dir <folder>] [--version <v>] [--no-secrets] [--json]\n                                                           one command, first deploy included: sends the\n                                                           .env's new or changed values as secrets, then\n                                                           packs, builds and follows it to live\n  flow deploy promote [--no-secrets] [--json]              staging's live version to production (the\n                                                           .env's new or changed values sent there first)\n  flow deploy status [--env staging|production] [--json]   what is live, its version, when, and its URL\n  flow deploy secret <NAME> [--env staging|production]     one secret, the value on stdin\n  flow deploy secrets --from-env [<file>] [--env staging|production]\n                                                           every value in <file> now (default: the agent's .env);\n                                                           flow deploy does this itself\n\n  --env        Where (default: staging). Production takes only an agent whose buildAgent passes\n               options.host on to createAgent, with no database of its own.\n  --dir        The agent's folder (default: .): package.json, package-lock.json, src/agent.ts.\n  --version    A label for this version (default: the folder's git commit, if any, with +dirty\n               when the folder has uncommitted changes).\n  --no-secrets Deploy without sending the .env's values as secrets.\n  --cloud      The cloud's address (default: FLOW_FRAMEWORK_CLOUD, else https://flow.engineer/observe).\n  --from-env   With secrets: send each non-empty value in the file as a secret (never the CI key,\n               the cloud's address, or a name Flow sets itself, such as the\n               FLOW_FRAMEWORK_TRACES_* that flow link writes). Prints names only.\n  --json       Print one JSON answer on stdout (progress goes to stderr).\n\nflow deploy (and deploy promote, for production) sends each non-empty .env value as a secret (the\nsame names as secrets --from-env sends) before the service starts, and later only the new or changed ones: .flow/secrets.json keeps a\nhash per name, never a value. It prints names only.\n\nstatus shows both environments unless --env names one. The last deploy this folder made is kept\nin .flow/deploys.json (never packed).\n\nEnvironment (or the agent folder's .env):\n  FLOW_FRAMEWORK_CLOUD_KEY   The agent's CI key (oci_...): flow setup writes it, or make one on\n                             your agent's Developers page. CHINWAG_CLOUD_KEY, its older name, works too.";
+/** Names the host sets on the agent's service itself, which it refuses as secrets. */
+export declare const HOST_NAMES: RegExp;
+/**
+ * Left out of the packed folder: dependencies (the build runs npm ci), git, every .env, and the
+ * framework's local results (.flow, .chinwag before the rename), which the hosted agent never reads.
+ */
+export declare const PACK_EXCLUDES: string[];
+export declare const MAX_BUNDLE: number;
+/**
+ * A .env file's names and values: NAME=value lines, `export ` allowed, values in single or double
+ * quotes taken as written (double quotes understand \n), an unquoted value up to a ` #` comment.
+ */
+export declare function parseEnv(text: string): Map<string, string>;
+/** The agent's folder as a .tgz at `bundle`, without PACK_EXCLUDES. */
+export declare function pack(dir: string, bundle: string): void;
+export interface DeployOptions {
+    /** Where the value of `flow deploy secret` comes from (default: stdin). */
+    readStdin?: () => string;
+    /** Milliseconds between looks at a building deploy, or new log lines with --follow (default 3000). */
+    pollMs?: number;
+    /** With `flow logs --follow`: stop after this many looks (tests); default never. */
+    maxPolls?: number;
+    /** The clock, for --since (tests). */
+    now?: () => number;
+}
+/** `flow deploy ...`. */
+export declare function deployCli(argv: string[], env?: NodeJS.ProcessEnv, options?: DeployOptions): Promise<number>;
+/** `flow logs ...`. */
+export declare function logsCli(argv: string[], env?: NodeJS.ProcessEnv, options?: DeployOptions): Promise<number>;
+/** --since as seconds: 30s, 15m, 1h, 2d. */
+export declare function sinceSeconds(since: string): number | undefined;
+/** The folder's git commit, with +dirty when the folder has changes not committed (what is packed is the folder as it is). */
+export declare function gitVersion(dir: string): string | undefined;