@foldrun/core 0.4.0 → 0.5.0

package/dist/src/step-removal.d.ts

@@ -0,0 +1,15 @@
+import type { FlowStep } from "./store.ts";
+export interface RemovalImpact {
+    /** "step 4 · watchdog" — the step as a person names it. */
+    label: string;
+    /** One sentence per consequence. */
+    notes: string[];
+}
+/** A step as a person names it: its group number and its target. */
+export declare function stepLabel(steps: FlowStep[], index: number): string;
+/**
+ * What else changes when step `index` goes — said before it goes, in the
+ * words a confirm dialog or a terminal prints. Nothing here refuses; it
+ * describes. removeStep refuses.
+ */
+export declare function removalImpact(steps: FlowStep[], index: number): RemovalImpact;

package/dist/src/step-removal.js

@@ -0,0 +1,49 @@
+// What deleting one step from a flow changes, in words — for the confirm
+// dialog on the canvas and the CLI's `flow rm-step`. Pure over parsed steps
+// and free of the parser and the filesystem, so the browser can import it.
+// The edit itself is flow-patterns.ts removeStep.
+function groupsOf(steps) {
+    const map = new Map();
+    steps.forEach((s, i) => map.set(s.group, [...(map.get(s.group) ?? []), i]));
+    return [...map.entries()].sort((a, b) => a[0] - b[0]).map(([, v]) => v);
+}
+/** A step as a person names it: its group number and its target. */
+export function stepLabel(steps, index) {
+    const s = steps[index];
+    const column = groupsOf(steps).findIndex((g) => g.includes(index));
+    return `step ${column + 1} · ${s.subflow ? `flow:${s.subflow}` : s.agent}`;
+}
+/**
+ * What else changes when step `index` goes — said before it goes, in the
+ * words a confirm dialog or a terminal prints. Nothing here refuses; it
+ * describes. removeStep refuses.
+ */
+export function removalImpact(steps, index) {
+    const s = steps[index];
+    if (!s)
+        throw new Error(`no step ${index + 1}`);
+    const groups = groupsOf(steps);
+    const column = groups.findIndex((g) => g.includes(index));
+    const alone = groups[column].length === 1;
+    const notes = [];
+    if (steps.length === 1)
+        notes.push("It is the flow's only step — the flow will have nothing to run.");
+    const next = groups[column + 1]?.map((i) => steps[i]) ?? [];
+    const routed = next.filter((t) => t.case !== undefined || t.else || t.when !== undefined);
+    if (alone && routed.length) {
+        const before = groups[column - 1];
+        const on = before ? `step ${column}'s result (${before.map((i) => steps[i].subflow ? `flow:${steps[i].subflow}` : steps[i].agent).join(", ")})` : "nothing — they would come first";
+        notes.push(`${routed.length === 1 ? "The case:/when: step" : `The ${routed.length} case:/when: steps`} after it (${routed.map((t) => t.subflow ?? t.agent).join(", ")}) will route on ${on}.`);
+    }
+    if (s.case !== undefined || s.else)
+        notes.push(`It is a branch (${s.case !== undefined ? `case: ${s.case}` : "else"}) — that route is gone.`);
+    if (alone && column < groups.length - 1) {
+        const from = column + 2, to = groups.length;
+        notes.push(from === to ? `Group ${from} after it renumbers to ${from - 1}.` : `The groups after it renumber: ${from}–${to} become ${from - 1}–${to - 1}.`);
+    }
+    if (!alone)
+        notes.push(`The ${groups[column].length - 1} other step${groups[column].length === 2 ? "" : "s"} in group ${column + 1} still run${groups[column].length === 2 ? "s" : ""}.`);
+    if (!s.subflow)
+        notes.push(`agents/${s.agent}/agent.md is not touched.`);
+    return { label: stepLabel(steps, index), notes };
+}

package/dist/src/storage.d.ts

@@ -60,7 +60,9 @@ export interface Driver {
     remove(key: string): Promise<void>;
     /** A URL a browser can GET directly, or null when the driver has no such
      *  thing (fs) and the route must stream the bytes itself. */
-    presignGet(key: string, filename: string, mime: string, ttlSec?: number): Promise<string | null>;
+    /** `inlineType`: show it rather than save it — only ever a type from
+     *  previewType(), which cannot run script. Anything else is attachment. */
+    presignGet(key: string, filename: string, mime: string, ttlSec?: number, inlineType?: string): Promise<string | null>;
     /** A URL a browser can PUT directly to, so upload bytes never transit the
      *  dashboard process. Null on fs, where the route takes the body. */
     presignPut(key: string, mime: string, ttlSec?: number): Promise<string | null>;
@@ -72,11 +74,25 @@ interface S3Config {
     endpoint: string;
     bucket: string;
     region: string;
-    accessKeyId: string;
-    secretAccessKey: string;
+    /** Static keys (R2, or a self-host with an IAM user). Absent: the pod's
+     *  role, read from the container credential endpoint — see credentials(). */
+    accessKeyId?: string;
+    secretAccessKey?: string;
     pathStyle: boolean;
 }
+/** `https://s3.ap-southeast-2.amazonaws.com` → `ap-southeast-2`. Null for
+ *  anything else (R2, MinIO), whose region is whatever the env says. */
+export declare function regionOfEndpoint(endpoint: string): string | null;
 export declare function s3Config(): S3Config | null;
+/** For tests: forget cached role credentials. */
+export declare function forgetS3Credentials(): void;
+/**
+ * The Content-Disposition a presigned GET asks the store to send back. The
+ * store echoes it as a header, and header values are bytes: a raw "報告.pdf"
+ * comes back mangled or refused. RFC 6266: an ASCII `filename` for old
+ * clients, the exact name percent-encoded as UTF-8 in `filename*`.
+ */
+export declare function contentDisposition(type: "inline" | "attachment", filename: string): string;
 /**
  * The driver in force. `fs` unless S3 is both selected and configured —
  * a half-set environment falls back rather than failing at the first upload,
@@ -90,7 +106,10 @@ export declare function registerUpload(tenant: string, workspace: string, rel: s
 export declare function readFileBytes(tenant: string, workspace: string, rel: string): Promise<Buffer | null>;
 export declare function deleteFile(tenant: string, workspace: string, rel: string): Promise<boolean>;
 /** A link the browser can follow, or null when the route must stream it. */
-export declare function downloadUrl(tenant: string, workspace: string, record: FileRecord): Promise<string | null>;
+export declare function downloadUrl(tenant: string, workspace: string, record: FileRecord, opts?: {
+    inline?: boolean;
+}): Promise<string | null>;
+export declare function previewType(rel: string): string | null;
 /** A link the browser can PUT to, plus the key it will land at. Null on fs. */
 export declare function uploadUrl(tenant: string, workspace: string, rel: string, sha: string): Promise<string | null>;
 /**

package/dist/src/storage.js

@@ -42,9 +42,9 @@
 //   FOLDRUN_S3_ENDPOINT         https://<account>.r2.cloudflarestorage.com
 //   FOLDRUN_S3_BUCKET           bucket name
 //   FOLDRUN_S3_REGION           default auto (R2's region)
-//   FOLDRUN_S3_ACCESS_KEY_ID
-//   FOLDRUN_S3_SECRET_ACCESS_KEY
-//   FOLDRUN_S3_PATH_STYLE       default true — R2 speaks path style
+//   FOLDRUN_S3_ACCESS_KEY_ID    static keys (R2); leave both unset under an
+//   FOLDRUN_S3_SECRET_ACCESS_KEY  AWS role — the pod's credentials are used
+//   FOLDRUN_S3_PATH_STYLE       default true — R2 speaks path style; false on S3
 //   FOLDRUN_STORAGE_MAX_MB        per object, default 512
 //   FOLDRUN_STORAGE_QUOTA_MB      per workspace, default 5120
 import fs from "node:fs";
@@ -222,23 +222,85 @@ function fsDriver(tenant, workspace) {
         },
     };
 }
+/** `https://s3.ap-southeast-2.amazonaws.com` → `ap-southeast-2`. Null for
+ *  anything else (R2, MinIO), whose region is whatever the env says. */
+export function regionOfEndpoint(endpoint) {
+    const m = /^s3[.-]([a-z]{2}-[a-z]+-\d)\.amazonaws\.com$/.exec(new URL(endpoint).host);
+    return m ? m[1] : null;
+}
+/** True when this process runs under an AWS role handed out through the
+ *  container credential endpoint — EKS Pod Identity, ECS, or an IRSA-style
+ *  shim. The endpoint is the pod's, and the token file is mounted beside it. */
+function containerCredentialsAvailable() {
+    return Boolean(process.env.AWS_CONTAINER_CREDENTIALS_FULL_URI || process.env.AWS_CONTAINER_CREDENTIALS_RELATIVE_URI);
+}
 export function s3Config() {
     const endpoint = process.env.FOLDRUN_S3_ENDPOINT;
     const bucket = process.env.FOLDRUN_S3_BUCKET;
     const accessKeyId = process.env.FOLDRUN_S3_ACCESS_KEY_ID;
     const secretAccessKey = process.env.FOLDRUN_S3_SECRET_ACCESS_KEY;
-    if (!endpoint || !bucket || !accessKeyId || !secretAccessKey)
+    if (!endpoint || !bucket)
+        return null;
+    const staticKeys = Boolean(accessKeyId && secretAccessKey);
+    // No key and no role is a half-set environment: fall back to fs rather
+    // than fail at the first upload (driverFor says why).
+    if (!staticKeys && !containerCredentialsAvailable())
         return null;
     return {
         endpoint: endpoint.replace(/\/+$/, ""),
         bucket,
-        // R2 has one region and calls it `auto`. AWS callers set their own.
-        region: process.env.FOLDRUN_S3_REGION ?? "auto",
-        accessKeyId,
-        secretAccessKey,
+        // R2 has one region and calls it `auto`. An AWS endpoint names its own;
+        // anything else says so in the env.
+        region: process.env.FOLDRUN_S3_REGION ?? regionOfEndpoint(endpoint) ?? "auto",
+        ...(staticKeys ? { accessKeyId, secretAccessKey } : {}),
         pathStyle: process.env.FOLDRUN_S3_PATH_STYLE !== "false",
     };
 }
+// ---------- credentials ----------
+//
+// Static keys are used as given. Without them, the process is running under
+// an AWS role: EKS Pod Identity (and ECS) publish the role's credentials on a
+// link-local HTTP endpoint named by AWS_CONTAINER_CREDENTIALS_FULL_URI, with
+// a bearer token read from AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE. They are
+// temporary — the reply says when — so they are cached and fetched again a
+// few minutes before they run out. This is the SDK's default chain, written
+// small: foldrun signs by hand and does not carry the SDK for this.
+let cached = null;
+const REFRESH_EARLY_MS = 5 * 60_000;
+async function credentials(cfg) {
+    if (cfg.accessKeyId && cfg.secretAccessKey)
+        return { accessKeyId: cfg.accessKeyId, secretAccessKey: cfg.secretAccessKey };
+    if (cached && Date.now() < cached.expiresAt - REFRESH_EARLY_MS)
+        return cached;
+    const full = process.env.AWS_CONTAINER_CREDENTIALS_FULL_URI;
+    const relative = process.env.AWS_CONTAINER_CREDENTIALS_RELATIVE_URI;
+    const url = full ?? (relative ? `http://169.254.170.2${relative}` : null);
+    if (!url)
+        throw new Error("s3: no static key and no container credential endpoint");
+    const headers = {};
+    const tokenFile = process.env.AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE;
+    const token = tokenFile ? fs.readFileSync(tokenFile, "utf8").trim() : process.env.AWS_CONTAINER_AUTHORIZATION_TOKEN;
+    if (token)
+        headers.authorization = token;
+    const res = await fetch(url, { headers, signal: AbortSignal.timeout(5_000) });
+    if (!res.ok)
+        throw new Error(`s3: the container credential endpoint answered ${res.status}`);
+    const body = (await res.json());
+    if (!body.AccessKeyId || !body.SecretAccessKey)
+        throw new Error("s3: the container credential endpoint returned no key");
+    cached = {
+        accessKeyId: body.AccessKeyId,
+        secretAccessKey: body.SecretAccessKey,
+        ...(body.Token ? { sessionToken: body.Token } : {}),
+        // No expiry in the reply: treat it as good for an hour, then ask again.
+        expiresAt: body.Expiration ? Date.parse(body.Expiration) : Date.now() + 60 * 60_000,
+    };
+    return cached;
+}
+/** For tests: forget cached role credentials. */
+export function forgetS3Credentials() {
+    cached = null;
+}
 const sha256 = (b) => crypto.createHash("sha256").update(b).digest("hex");
 const hmac = (key, data) => crypto.createHmac("sha256", key).update(data, "utf8").digest();
 /** RFC 3986. encodeURIComponent leaves !'()* alone and SigV4 does not. */
@@ -250,8 +312,8 @@ function stamps(now) {
     const amzDate = now.toISOString().replace(/[-:]/g, "").replace(/\.\d{3}/, "");
     return { amzDate, dateStamp: amzDate.slice(0, 8) };
 }
-function signingKey(cfg, dateStamp) {
-    const kDate = hmac(`AWS4${cfg.secretAccessKey}`, dateStamp);
+function signingKey(cfg, creds, dateStamp) {
+    const kDate = hmac(`AWS4${creds.secretAccessKey}`, dateStamp);
     const kRegion = hmac(kDate, cfg.region);
     const kService = hmac(kRegion, "s3");
     return hmac(kService, "aws4_request");
@@ -276,17 +338,20 @@ function target(cfg, key) {
  * wrote can never render as a page on any origin. Without it, "the agent
  * produced a report.html" and "stored XSS" are the same event.
  */
-function presign(cfg, method, key, ttlSec, extraQuery = {}, now = new Date()) {
+function presign(cfg, creds, method, key, ttlSec, extraQuery = {}, now = new Date()) {
     const { host, origin, canonicalUri } = target(cfg, key);
     const { amzDate, dateStamp } = stamps(now);
     const scope = `${dateStamp}/${cfg.region}/s3/aws4_request`;
     const query = {
         ...extraQuery,
         "X-Amz-Algorithm": "AWS4-HMAC-SHA256",
-        "X-Amz-Credential": `${cfg.accessKeyId}/${scope}`,
+        "X-Amz-Credential": `${creds.accessKeyId}/${scope}`,
         "X-Amz-Date": amzDate,
         "X-Amz-Expires": String(ttlSec),
         "X-Amz-SignedHeaders": "host",
+        // A role's credentials are only valid with their token, and the token
+        // is part of what is signed.
+        ...(creds.sessionToken ? { "X-Amz-Security-Token": creds.sessionToken } : {}),
     };
     const canonicalQuery = Object.keys(query)
         .sort()
@@ -306,11 +371,12 @@ function presign(cfg, method, key, ttlSec, extraQuery = {}, now = new Date()) {
         scope,
         sha256(canonicalRequest),
     ].join("\n");
-    const signature = hmac(signingKey(cfg, dateStamp), stringToSign).toString("hex");
+    const signature = hmac(signingKey(cfg, creds, dateStamp), stringToSign).toString("hex");
     return `${origin}${canonicalUri}?${canonicalQuery}&X-Amz-Signature=${signature}`;
 }
 /** The header-signed form, for the calls the platform itself makes. */
 async function s3Request(cfg, method, key, body, mime) {
+    const creds = await credentials(cfg);
     const { host, origin, canonicalUri } = target(cfg, key);
     const { amzDate, dateStamp } = stamps(new Date());
     const scope = `${dateStamp}/${cfg.region}/s3/aws4_request`;
@@ -319,6 +385,7 @@ async function s3Request(cfg, method, key, body, mime) {
         host,
         "x-amz-content-sha256": payloadHash,
         "x-amz-date": amzDate,
+        ...(creds.sessionToken ? { "x-amz-security-token": creds.sessionToken } : {}),
         ...(mime ? { "content-type": mime } : {}),
     };
     const signed = Object.keys(headers).sort();
@@ -333,13 +400,13 @@ async function s3Request(cfg, method, key, body, mime) {
         payloadHash,
     ].join("\n");
     const stringToSign = ["AWS4-HMAC-SHA256", amzDate, scope, sha256(canonicalRequest)].join("\n");
-    const signature = hmac(signingKey(cfg, dateStamp), stringToSign).toString("hex");
+    const signature = hmac(signingKey(cfg, creds, dateStamp), stringToSign).toString("hex");
     const res = await fetch(`${origin}${canonicalUri}`, {
         method,
         body: body,
         headers: {
             ...headers,
-            Authorization: `AWS4-HMAC-SHA256 Credential=${cfg.accessKeyId}/${scope}, ` +
+            Authorization: `AWS4-HMAC-SHA256 Credential=${creds.accessKeyId}/${scope}, ` +
                 `SignedHeaders=${signedHeaders}, Signature=${signature}`,
         },
     });
@@ -372,18 +439,32 @@ function s3Driver(cfg) {
             if (!res.ok && res.status !== 404)
                 await fail(res, "delete");
         },
-        async presignGet(key, filename, mime, ttlSec = 300) {
-            return presign(cfg, "GET", key, ttlSec, {
-                // Never inline. See presign()'s note — this is the XSS boundary.
-                "response-content-disposition": `attachment; filename="${filename.replace(/["\\]/g, "")}"`,
-                "response-content-type": mime,
+        async presignGet(key, filename, mime, ttlSec = 300, inlineType) {
+            // Attachment, unless the caller names a preview type — and then only a
+            // type previewType() vouches for, with that type forced, so a stored
+            // page can never come back as a page. See presign()'s note.
+            const safe = inlineType && PREVIEW_TYPES_SET.has(inlineType) ? inlineType : null;
+            return presign(cfg, await credentials(cfg), "GET", key, ttlSec, {
+                "response-content-disposition": contentDisposition(safe ? "inline" : "attachment", filename),
+                "response-content-type": safe ?? mime,
             });
         },
         async presignPut(key, _mime, ttlSec = 600) {
-            return presign(cfg, "PUT", key, ttlSec);
+            return presign(cfg, await credentials(cfg), "PUT", key, ttlSec);
         },
     };
 }
+/**
+ * The Content-Disposition a presigned GET asks the store to send back. The
+ * store echoes it as a header, and header values are bytes: a raw "報告.pdf"
+ * comes back mangled or refused. RFC 6266: an ASCII `filename` for old
+ * clients, the exact name percent-encoded as UTF-8 in `filename*`.
+ */
+export function contentDisposition(type, filename) {
+    const ascii = filename.replace(/[^\x20-\x7e]/gu, "_").replace(/["\\]/g, "_");
+    const exact = encodeURIComponent(filename).replace(/['()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`);
+    return `${type}; filename="${ascii}"; filename*=UTF-8''${exact}`;
+}
 /**
  * The driver in force. `fs` unless S3 is both selected and configured —
  * a half-set environment falls back rather than failing at the first upload,
@@ -518,8 +599,29 @@ async function collect(tenant, workspace, sha) {
     }
 }
 /** A link the browser can follow, or null when the route must stream it. */
-export async function downloadUrl(tenant, workspace, record) {
-    return driverFor(tenant, workspace).presignGet(blobKey(tenant, workspace, record.sha), path.basename(record.path), record.mime);
+export async function downloadUrl(tenant, workspace, record, opts = {}) {
+    const inlineType = opts.inline ? previewType(record.path) ?? undefined : undefined;
+    return driverFor(tenant, workspace).presignGet(blobKey(tenant, workspace, record.sha), path.basename(record.path), record.mime, 300, inlineType);
+}
+/**
+ * The types a stored file may be shown as, rather than saved: pictures,
+ * video, audio and PDF, by extension. None of them runs script in a page —
+ * SVG is left out for exactly that reason, and so is anything HTML-shaped.
+ * Null means "download it".
+ */
+const PREVIEW_TYPES = {
+    ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".jfif": "image/jpeg", ".webp": "image/webp", ".gif": "image/gif", ".avif": "image/avif",
+    ".bmp": "image/bmp", ".ico": "image/x-icon", ".cur": "image/x-icon", ".apng": "image/apng",
+    ".mp4": "video/mp4", ".webm": "video/webm", ".mov": "video/quicktime", ".m4v": "video/mp4", ".mkv": "video/x-matroska",
+    ".ogv": "video/ogg", ".3gp": "video/3gpp", ".3gpp": "video/3gpp", ".3g2": "video/3gpp2", ".mpg": "video/mpeg", ".mpeg": "video/mpeg", ".avi": "video/x-msvideo",
+    ".mp3": "audio/mpeg", ".wav": "audio/wav", ".m4a": "audio/mp4", ".m4r": "audio/mp4", ".m4b": "audio/mp4", ".aac": "audio/aac",
+    ".ogg": "audio/ogg", ".oga": "audio/ogg", ".opus": "audio/ogg", ".flac": "audio/flac", ".aif": "audio/aiff", ".aiff": "audio/aiff", ".weba": "audio/webm",
+    ".pdf": "application/pdf", ".ai": "application/pdf",
+    ".ttf": "font/ttf", ".otf": "font/otf", ".woff": "font/woff", ".woff2": "font/woff2",
+};
+const PREVIEW_TYPES_SET = new Set(Object.values(PREVIEW_TYPES));
+export function previewType(rel) {
+    return PREVIEW_TYPES[path.extname(rel).toLowerCase()] ?? null;
 }
 /** A link the browser can PUT to, plus the key it will land at. Null on fs. */
 export async function uploadUrl(tenant, workspace, rel, sha) {