@foldrun/core 0.4.0 → 0.6.0

package/src/step-removal.ts

@@ -0,0 +1,59 @@
+// 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.
+
+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[];
+}
+
+function groupsOf(steps: FlowStep[]): number[][] {
+  const map = new Map<number, number[]>();
+  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: FlowStep[], index: number): string {
+  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: FlowStep[], index: number): RemovalImpact {
+  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: string[] = [];
+  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/src/storage.ts

@@ -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
 
@@ -227,7 +227,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>;
@@ -280,9 +282,33 @@ interface S3Config {
   endpoint: string;
   bucket: string;
   region: 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;
+}
+
+/** What signs a request: a key pair, and a session token when the pair is
+ *  temporary (a role's). The token rides in every signed request. */
+interface Credentials {
   accessKeyId: string;
   secretAccessKey: string;
-  pathStyle: boolean;
+  sessionToken?: string;
+}
+
+/** `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: string): string | null {
+  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(): boolean {
+  return Boolean(process.env.AWS_CONTAINER_CREDENTIALS_FULL_URI || process.env.AWS_CONTAINER_CREDENTIALS_RELATIVE_URI);
 }
 
 export function s3Config(): S3Config | null {
@@ -290,18 +316,65 @@ export function s3Config(): S3Config | null {
   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) return null;
+  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: (Credentials & { expiresAt: number }) | null = null;
+const REFRESH_EARLY_MS = 5 * 60_000;
+
+async function credentials(cfg: S3Config): Promise<Credentials> {
+  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: Record<string, string> = {};
+  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()) as { AccessKeyId?: string; SecretAccessKey?: string; Token?: string; Expiration?: string };
+  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(): void {
+  cached = null;
+}
+
 // Narrower than crypto.BinaryLike on purpose. BinaryLike also covers views
 // over a SharedArrayBuffer, which .update() has never accepted and which
 // @types/node 26 finally says so about — the old typings let this compile by
@@ -326,8 +399,8 @@ function stamps(now: Date) {
   return { amzDate, dateStamp: amzDate.slice(0, 8) };
 }
 
-function signingKey(cfg: S3Config, dateStamp: string) {
-  const kDate = hmac(`AWS4${cfg.secretAccessKey}`, dateStamp);
+function signingKey(cfg: S3Config, creds: Credentials, dateStamp: string) {
+  const kDate = hmac(`AWS4${creds.secretAccessKey}`, dateStamp);
   const kRegion = hmac(kDate, cfg.region);
   const kService = hmac(kRegion, "s3");
   return hmac(kService, "aws4_request");
@@ -356,6 +429,7 @@ function target(cfg: S3Config, key: string) {
  */
 function presign(
   cfg: S3Config,
+  creds: Credentials,
   method: "GET" | "PUT",
   key: string,
   ttlSec: number,
@@ -369,10 +443,13 @@ function presign(
   const query: Record<string, string> = {
     ...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()
@@ -395,7 +472,7 @@ function presign(
     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}`;
 }
 
@@ -407,6 +484,7 @@ async function s3Request(
   body?: Buffer,
   mime?: string,
 ): Promise<Response> {
+  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`;
@@ -416,6 +494,7 @@ async function s3Request(
     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();
@@ -432,7 +511,7 @@ async function s3Request(
   ].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,
@@ -440,7 +519,7 @@ async function s3Request(
     headers: {
       ...headers,
       Authorization:
-        `AWS4-HMAC-SHA256 Credential=${cfg.accessKeyId}/${scope}, ` +
+        `AWS4-HMAC-SHA256 Credential=${creds.accessKeyId}/${scope}, ` +
         `SignedHeaders=${signedHeaders}, Signature=${signature}`,
     },
   });
@@ -471,19 +550,34 @@ function s3Driver(cfg: S3Config): Driver {
       // 404 on delete is the desired end state, not an error.
       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: "inline" | "attachment", filename: string): string {
+  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,
@@ -646,14 +740,39 @@ export async function downloadUrl(
   tenant: string,
   workspace: string,
   record: FileRecord,
+  opts: { inline?: boolean } = {},
 ): Promise<string | null> {
+  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: Record<string, string> = {
+  ".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: string): string | null {
+  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: string,